Microsoft 365 MCP Server

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

Annotations indicate this is a destructive (destructiveHint: true), non-read-only (readOnlyHint: false) operation, which aligns with the 'create' action. The description adds useful context about the default notebook constraint and how to target different sections, but doesn't disclose additional behavioral traits like authentication requirements, rate limits, or error conditions. No contradiction with annotations exists.

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 at three sentences but has structural issues. The first sentence clearly states the purpose, but the second sentence introduces an example with URL syntax that interrupts the flow. The third sentence repeats information about the default notebook. Some redundancy exists, and the example could be better integrated.

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 (3 parameters with nested objects, 67% schema coverage, no output schema, and destructive annotations), the description is moderately complete. It covers the main use case and constraints but lacks details on required permissions, error handling, response format, or how to handle the complex 'body' parameter structure beyond what the schema provides.

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 67%, with the 'body' parameter having extensive nested documentation. The description adds semantic context by mentioning the 'sectionName query parameter' for targeting different sections, which isn't explicitly documented in the schema. However, it doesn't explain the purpose of 'includeHeaders' or 'excludeResponse' parameters, leaving gaps in parameter understanding.

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 creates a new OneNote page with specific location constraints ('in the default section of the default notebook'). It uses the verb 'create' with the resource 'OneNote page', making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'create-excel-chart' or 'create-planner-task' beyond the resource name.

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 about when to use this tool versus alternatives: it specifies this is for creating pages in the 'current user's default notebook' and mentions that for other notebooks, you need to 'create pages in a specified section.' It also shows how to target different sections via the sectionName parameter. However, it doesn't explicitly name alternative tools or state when NOT to use this tool.

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