eduframe-mcp

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

With no annotations provided, the description carries full responsibility for behavioral disclosure but provides none. It does not explain the order lifecycle state after creation (draft vs pending), financial implications (whether payment is immediate), idempotency, or the meaning of the 'approve' parameter in the creation context.

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?

While brief (two words), this represents under-specification rather than efficient conciseness. For a complex tool with 13 parameters including nested objects, financial fields (cost, payment_method_id), and deprecated fields, the description is inappropriately sized and front-loaded with zero useful 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?

Completely inadequate for the complexity level. The tool has 13 parameters, nested objects, enum constraints, deprecated fields, and no output schema or annotations. The description addresses none of the complexity: no return value documentation, no workflow context, no error conditions, and no explanation of the cost_scheme enum implications.

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?

Input schema has 100% description coverage, establishing baseline 3. However, the description adds no context about parameter relationships (e.g., the mutual exclusivity between student_ids and enrollments_attributes mentioned in schema descriptions) or the deprecation of planned_course_id in favor of catalog_variant_id.

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 'Create an order.' is tautological, merely restating the tool name without distinguishing it from siblings like approve_order, cancel_order, or deny_order. It fails to clarify what distinguishes 'creating' an order from other order lifecycle operations available in the sibling set.

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?

No guidance provided on when to use this tool versus alternatives, nor prerequisites for invocation. The description omits the evident workflow implications (e.g., relationship to approve_order, whether creation requires subsequent approval) and fails to mention that account_id defaults to personal account if omitted.

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