onenote_list_notebooksLists your OneNote notebooks with their section groups and sections, including IDs, so you can locate the section IDs needed for other operations.
Lists the user's OneNote notebooks with their section groups and sections (IDs included). Start here to find section IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| include_sections | No | Include the section/section-group tree under each notebook. |
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, so the description doesn't need to argue safety. It usefully adds that IDs are returned and that the tree is nested, but says nothing about sign-in/auth prerequisites (relevant given onenote_sign_in is a sibling) or result-size/pagination behavior for large accounts.
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 short sentences, no filler, with the scope and returned payload front-loaded and the usage cue second. Every clause earns its place.
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 one-parameter read tool with no output schema, the description is nearly sufficient: it covers scope, returned contents, and when to reach for it. The only meaningful omission is the authentication prerequisite, which matters in a toolset that includes explicit sign-in/sign-out siblings.
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% and the single include_sections parameter is fully documented in the schema, so the schema carries the weight. The description only hints at the parameter's effect by promising 'section groups and sections' in the output, without adding format or default-behavior detail beyond the schema.
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?
States a specific verb (Lists) and resource (the user's OneNote notebooks) and clarifies that the response includes the section group/section tree with IDs. It is clearly distinguishable from onenote_list_sections and onenote_list_pages by the notebook-level scope, though it never names those siblings explicitly.
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?
'Start here to find section IDs' gives a concrete entry-point cue and an implied workflow (list notebooks -> get section IDs -> act on sections). It stops short of naming the alternative tools or the condition under which you'd skip this and call onenote_list_sections directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.