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

With no annotations provided, the description carries the full burden of disclosure. It communicates a read-only diagnostic behavior and spells out the three pieces of status it reports, which goes beyond a mere label. It stops short of explicitly stating side-effect-freedom or how token validation is performed, but the framing as a status report is sufficiently transparent.

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 sentences, no filler: the first front-loads what the tool reports and the second provides a concrete usage trigger. Every sentence 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 parameterless diagnostic tool, this is complete: it states the tool's outputs, implies its non-destructive nature, and gives an explicit scenario for invocation. No output schema exists, but the description names the exact information an agent would need from the call.

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 tool has zero parameters, so schema coverage is trivially complete and there is no parameter burden to compensate for. The baseline of 4 applies; the description adds meaning about what the tool reports, though parameter-specific semantics are not applicable.

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 uses a specific verb ('Reports') and names concrete outputs (account identity, token cache location, token validity), making the tool's purpose unmistakable. It also contrasts with all sibling OneNote tools, which operate on notebooks/pages rather than authentication state.

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?

Explicitly instructs when to invoke: 'Use it first when a OneNote call fails with an authentication error.' This gives the agent a clear trigger and ordering rule; no alternative auth tool exists among siblings, so no exclusion is needed.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does disclose the key non-destructive nature: 'the source page is left untouched — this never moves or deletes anything.' This is valuable. However, it omits other behavioral details such as whether child pages are copied, what happens to permissions, or any prerequisites. For a copy tool, the non-destructive guarantee is essential but not exhaustive.

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 two sentences with zero fluff. The primary action is front-loaded ('Copies a page into another section'), and the critical clarification about non-destructive behavior follows immediately. Every word earns its place, making it highly efficient.

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 simple copy tool with two parameters and no output schema, the description covers the essential behavior: what it does and that it is non-destructive. It does not describe the copy's scope (e.g., subpages, attachments) or error conditions, but these are not essential for basic invocation. Given the simplicity and clear purpose, the description is sufficiently complete for an agent to use it correctly.

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 input schema has 100% coverage, with clear descriptions for both pageId ('ID of the page to copy') and targetSectionId ('ID of the section to copy the page into'). The description adds no additional meaning beyond the schema, so it does not improve parameter understanding. Baseline of 3 is appropriate since the schema already documents the parameters fully.

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 action: 'Copies a page into another section', with a specific verb and resource. It further distinguishes itself from move/delete operations by explicitly stating 'the source page is left untouched — this never moves or deletes anything.' This differentiates it from sibling tools like delete_page and update_page, making the purpose unmistakable.

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 gives a clear context of use: duplicating a page into a different section. It also provides a negative constraint ('never moves or deletes anything') which implicitly tells the agent this is not for moving pages. However, it does not explicitly name alternative tools or provide when-to-use/when-not-to-use comparisons, though the purpose is self-evident. This is strong but not fully explicit.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It only states the creation action, which implies mutation, but does not disclose permissions, reversibility, return behavior, or error conditions (e.g., duplicate name handling). The uniqueness constraint appears only in the parameter schema, not in the description itself, leaving the agent without critical behavioral 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?

The description is a single, front-loaded sentence with no unnecessary words. It states the action and the key attribute (top-level) immediately, and every word contributes to the meaning. Efficient and well-structured.

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 simple one-parameter tool with no output schema and no annotations, the description is minimally adequate. However, it omits any mention of the return value (does it return the created notebook?), which could be relevant for an agent chaining actions. It also does not clarify the meaning of 'top-level' beyond what the schema implies. These gaps leave the tool slightly under-specified for full contextual understanding.

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 coverage is 100%, with the parameter 'name' fully described (display name, uniqueness, reserved characters). The description adds minimal value by saying 'given display name', but this only restates the parameter name. Since the schema already carries the semantic load, the description doesn't need to compensate, and a baseline of 3 is appropriate.

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 states the exact action ('creates a new top-level OneNote notebook') with a specific resource type and scope ('top-level'). It clearly distinguishes from sibling creation tools like create_section, create_section_group, and create_page by indicating it targets notebooks specifically. The phrase 'given display name' ties the action to the parameter.

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 no guidance on when to use this tool versus alternatives. It does not mention that create_section or create_section_group should be used for nested elements, nor does it offer any exclusions or prerequisites. Usage context is only implied by the resource type, not explicitly stated.

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

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

No annotations are provided, so the description carries the burden. It discloses that Markdown is converted to HTML, HTML is sent directly (wrapped if fragment), and attachments are referenced via name:<name> URIs. It also mentions path traversal rejection for attachments, which is a useful behavioral constraint. It doesn't mention auth requirements or what happens on failure, but for a create tool the core behavior is well covered.

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 sentences, front-loaded with the core action, then the key format and attachment details. Every clause earns its place. The attachment reference syntax is compactly included without bloating the description.

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 create tool with 5 parameters and no output schema, the description covers the essential behavior: what it creates, where, in what formats, and how attachments work. It doesn't explain return values, but no output schema exists and the schema covers parameters. It could mention auth requirements or idempotency, but those are less critical for a create operation.

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%, so the schema already documents all parameters. The description adds value by explaining the relationship between content and attachments (name:<name> URIs) and the format conversion behavior. It doesn't repeat parameter details but adds cross-parameter semantics that the schema doesn't fully convey.

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 states a specific verb ('Creates'), a resource ('a new OneNote page'), and the target location ('in the given section'). It also distinguishes itself from siblings by mentioning Markdown/HTML support and attachments, which are unique to page creation. This clearly differentiates it from update_page, delete_page, and read_page.

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 implies when to use it: when creating a page in a section. It doesn't explicitly say 'use this instead of update_page' or list alternatives, but the context is clear. It also gives format guidance (Markdown default, HTML option) and attachment usage, which helps the agent decide. It lacks explicit exclusions or when-not-to-use guidance, so not a 5.

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

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

With no annotations, the description itself must disclose behavioral expectations. It states the core mutation and the exclusive-parent rule, but it does not say what happens when both or neither ID is provided, whether special permissions are needed, or what the successful response contains.

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 a single front-loaded sentence plus one short operational constraint, with no redundant clauses. Every part of it contributes to correct selection or invocation.

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 low-complexity create operation with three self-documenting parameters, the description is nearly sufficient: it names the action, the parent choices, and the required exclusivity. The only notable omission is explicit return-value or error behavior, but that does not block an agent from invoking the tool correctly with the input 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?

Schema description coverage is 100%: name already documents the reserved characters and uniqueness requirement, and both parent IDs already document their exclusive relationship. The description repeats only the one-of rule and adds no new parameter-level meaning, so the baseline score applies.

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 names the exact operation ('Creates a new section') and the allowed parents ('inside the given notebook or section group'), which is enough to tell it apart from sibling create tools such as create_notebook, create_section_group, and create_page. It clearly identifies the resource being produced.

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 second sentence gives a precise invocation constraint: exactly one of notebookId or sectionGroupId must be supplied. However, it never states when an agent should choose this tool over the sibling create tools, and it does not describe exclusions or prerequisites beyond the parent requirement.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses the key input constraint (mutually exclusive parent IDs) and the creation action, but it does not mention side effects, permissions, error behaviors, or what happens on success. The exclusivity rule adds meaningful behavioral context, but the overall transparency is minimal beyond that.

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 sentences with zero filler. The first sentence states the action and destination, and the second provides the critical exclusivity constraint. The structure front-loads the primary purpose and adds needed constraint detail, making every word earn 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 simple creation tool with three parameters and no output schema, the description covers the essential decision rule (which parent ID to use) and the action itself. It lacks details on return value or failure modes, but these are not critical for selection and invocation. Given the simplicity, the description is nearly complete, though slightly sparse on post-creation behavior.

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?

Although schema coverage is 100%, the description adds semantic value by explaining the relationship between parameters: the new section group is placed 'inside the given notebook or another section group', and it explicitly states the exclusivity rule that the schema only hints at. This clarifies the roles of notebookId and sectionGroupId beyond their individual descriptions.

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 states a specific verb ('creates') and a specific resource ('section group'), and distinguishes it from sibling tools like create_section by explicitly naming the resource type. The parent-location detail further clarifies what the tool does, making it unambiguous what an agent would use it for.

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 by stating the resource and the parent-selection rule ('Exactly one of notebookId or sectionGroupId must be provided'), which implies when to use which parameter. However, it does not explicitly compare against alternatives like create_section or create_notebook, nor does it state when not to use this tool, so the guidance is implied rather than explicit.

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

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

Beyond the annotations (idempotentHint and destructiveHint), the description adds critical behavioral context: the deletion is permanent, there is no undo, and user confirmation is required. This is exactly the kind of additional transparency an agent needs for a destructive 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?

Two short sentences with no filler. The most important fact (permanent deletion) is front-loaded, and the actionable guardrail (confirm with user) follows immediately.

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 single-parameter destructive tool with no output schema, the description provides all essential information: what is deleted, that it is irreversible, and that user confirmation is required. Annotations cover safety and idempotency, so nothing critical is missing.

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 input schema has 100% coverage and fully describes pageId, including its irreversibility. The description only says 'by ID', adding little semantic value beyond the schema, so the baseline score of 3 is appropriate.

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 states a specific verb and resource: 'Permanently deletes a OneNote page by ID.' This clearly distinguishes it from sibling tools like update_page or copy_page and leaves no ambiguity about what operation is performed.

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 gives a clear and important usage guardrail: 'confirm with the user before calling' and emphasizes that there is no undo. It does not explicitly name alternatives or when-not-to-use conditions, but for a destructive deletion tool the context is clear.

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

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

With no annotations, the description carries the behavioral burden obliquely. It discloses that this is a search-style read operation, can span the whole account, and that the content pass downloads pages and is slower. It does not mention auth or rate limits, but for a read-only search tool the key behavioral traits are present and consistent.

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 sentences, front-loaded with the core purpose and return value, then the scoping modes and the sibling alternative. Every sentence earns its place and there is no filler.

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 6-parameter tool with no output schema and no annotations, the description covers the main things an agent needs: what it searches, what it returns, how scoping works, and when to prefer it over search_pages. It is not exhaustive about edge cases like conflicting scopes or exact response structure, but it is strong enough for correct selection and invocation.

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 each parameter already has a meaningful description with defaults and tradeoffs. The tool description adds scoping context but does not add significant parameter-level semantics beyond what the schema already provides.

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 opens with a specific verb and resource: 'Searches OneNote pages by text,' and states exactly what is returned (page IDs, titles, location). It also clearly distinguishes itself from search_pages, so an agent can tell them apart without opening the sibling tool.

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 explicitly positions this as the 'working alternative to search_pages' and explains why search_pages is unreliable (Graph endpoint rejects requests). It also names the three scoping modes (section, notebook, whole account), making the choice of when to use it concrete.

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

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

No annotations are provided, so the description carries the burden. It discloses the mapping behavior and the optional page-count cost ('Costs one extra request per 100 pages per section, so it is slow on large accounts'), which is useful. However, it doesn't disclose the return shape, whether it includes empty sections, or any auth requirements. The cost disclosure is a solid addition, but the overall behavioral context is incomplete.

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 sentences, front-loaded with the core purpose and the key use case. The cost warning is placed in the parameter description, not the main description, keeping the main text tight. Every sentence 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 read-only mapping tool with 2 optional params and no output schema, the description covers the purpose, the use case, and the main cost caveat. It doesn't describe the return format, but the tool's name and purpose make the tree structure predictable. The missing return shape is a minor gap, not a critical one.

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 coverage is 100%, so the schema already documents both parameters. The description adds context for includePageCounts (cost and slowness) beyond the schema's 'Costs one extra request...' note, but the schema already covers the semantics. Baseline 3 is appropriate.

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 states a specific verb ('Maps') and resource ('OneNote structure: notebooks, section groups, sections with IDs'), and distinguishes itself from siblings by naming the tools it feeds (list_pages, create_page, find_pages). An agent can tell it apart from list_notebooks or list_sections without opening schemas.

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?

Explicitly says 'Start here when you need section IDs for list_pages, create_page, or find_pages.' This gives a clear when-to-use directive and names the downstream tools that depend on it. It also implies when not to use it (when you only need notebooks, use list_notebooks), though it doesn't name that sibling explicitly.

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

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

Annotations are absent, so the description carries the behavioral disclosure burden. It discloses offline versus online behavior, Graph cost, and that sync/rebuild can take minutes. It does not discuss staleness, cache lifecycle, or rebuild effects in depth, but the core behavioral profile is communicated clearly.

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 two sentences with the core mechanism and value proposition front-loaded, followed by a cost/usage caveat. There is no filler, no restating of schema content, and 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?

Given full schema coverage and no output schema, the description covers purpose, cost model, and mode selection well. It lacks explicit guidance against sibling search_pages and does not explain rebuildSkeleton behavior, but the schema supplies mode details, so it is mostly complete.

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 input schema already describes all seven parameters with 100% coverage, so the baseline is 3. The description adds a practical hint that `sections` can scope sync to avoid long Graph walks, but it does not meaningfully redefine or enrich parameter semantics beyond what the schema already provides.

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 opens with a specific action and resource: it 'Maintains a local mirror of the OneNote structure (notebook/section/page names and IDs)'. It also distinguishes the tool from online Graph-backed lookup/search by emphasizing offline search and instant results, separating it from siblings like search_pages. The purpose is concrete and not a tautology.

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?

Provides clear context that search and status are offline while sync/rebuild hit Graph, and explicitly recommends to 'prefer sync, and scope it with sections when you know what changed.' It does not name alternative sibling tools or state explicit exclusion cases, but the offline/performance distinction gives practical decision guidance.

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

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

There are no annotations, so the description carries the behavioral burden. It does disclose that this is a read-only listing operation scoped to the signed-in user, but it omits details such as authentication prerequisites, pagination, ordering, or which metadata beyond IDs is returned. Adequate for a simple list, but not rich.

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?

A single front-loaded sentence clearly states the action, the resource, the scope, and the practical value of the result. There is no filler, no repetition of the title, and no content that duplicates the schema.

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 low-complexity, zero-parameter listing tool with no output schema, the description is nearly complete: it says what is listed, for whom, and what the caller can do with the result (obtain notebook IDs for other tools). It does not mention auth or pagination, but those are not required to invoke a no-argument list call correctly.

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 input schema has no properties and there are zero required parameters, so there are no parameters needing clarification. The description's mention of notebook IDs is output-oriented rather than parameter-oriented; the zero-parameter baseline of 4 applies.

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 uses a specific verb ('Lists'), a specific resource ('OneNote notebooks'), and a clear scope ('accessible to the signed-in user'). It also states the key outcome — 'notebook IDs needed for other tools' — which clearly separates this from sibling tools like list_sections or get_notebook_tree.

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 implies when to use it: when you need all notebooks and their IDs for downstream tools. However, it never explicitly says when NOT to use it or how it compares to alternatives such as get_notebook_tree, so usage guidance is left to inference.

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

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

No annotations are provided, so the description carries the full burden. It discloses a significant behavioral trait: the Graph API rejects account-wide page listing on accounts with many sections, forcing scoping by section or notebook. This is a valuable constraint that affects how the tool can be invoked. It does not explicitly state that it is a read-only operation, but 'lists' implies that. It also doesn't mention pagination behavior or error handling, but the disclosed limitation is the most important behavioral aspect. This is reasonably transparent.

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 two sentences with no waste. The first sentence states the core purpose and scope, and the second sentence provides a crucial constraint. It is front-loaded with the main action and clearly structured. Every word 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?

There is no output schema, so the description should at least hint at what the tool returns. It mentions 'get page IDs,' which implies the output includes page identifiers. It does not explain the full return format (e.g., whether it includes titles, links, etc.), but for a list tool with well-documented parameters and a clear purpose, this is acceptable. The description also covers the key operational caveat (no account-wide listing). It is sufficiently complete for an agent to invoke it correctly, though it could be slightly richer on return details.

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%, so all five parameters are already well-documented in the schema. The description adds only a small amount of semantic context: it reiterates the scoping concept ('scope by section or notebook') and mentions that listing across a notebook includes all sections, but this is already stated in the schema for notebookId. The description also hints that no search term is needed, which is not directly about parameters. Since the schema does the heavy lifting, the description's added value is marginal, so a baseline of 3 is appropriate.

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 function: 'Lists pages in a OneNote section, or across every section of a notebook, without needing a search term.' It specifies the resource (pages) and scope (section/notebook), and distinguishes itself from search_pages by explicitly saying 'without needing a search term.' The purpose of browsing and retrieving page IDs is also mentioned.

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 gives clear context: use it to browse and get page IDs. It also provides a critical usage constraint: 'there is no account-wide page listing — Graph rejects it on accounts with many sections, so scope by section or notebook.' This implicitly steers agents away from using it without scope and toward providing either sectionId or notebookId. It does not explicitly mention alternatives like search_pages for text-based searches, but the 'without needing a search term' phrase implies the contrast. Overall, it's clear but could be more explicit about when not to use it.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states the basic action and optional scoping; it does not disclose whether the returned list is flat or hierarchical, whether nested section groups are included, any pagination behavior, or what the response structure looks like. This is a significant gap for a tool that lists potentially nested structures.

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 a single, efficient sentence that front-loads the primary action and resource, then adds the scoping caveat. No wasted words.

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?

The tool is simple (one optional parameter, no output schema), and the description covers the core behavior. However, it leaves ambiguity about whether the listing includes nested section groups recursively or just top-level ones, and does not specify the return format. For an agent deciding whether this tool meets its need, that ambiguity is a notable gap.

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 coverage is 100% (the single parameter notebookId is described in the schema as optional and explains the behavior when omitted). The tool description adds little beyond the schema—it only restates 'optionally scoped to a single notebook', which is less detailed than the schema. Baseline of 3 is appropriate since the schema already documents the parameter.

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 verb 'Lists' and the resource 'section groups', and even defines what section groups are (folders containing sections and/or other section groups). It distinguishes the resource from siblings like list_sections or list_notebooks by naming the specific object type, but it does not explicitly name an alternative tool to differentiate from.

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 mentions optional scoping to a notebook, giving context on the notebookId parameter, but it provides no guidance on when to use this tool versus list_sections, get_notebook_tree, or other listing tools. There is no when/when-not or explicit alternative mentioned.

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

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, but it only restates the listing action and scope. It does not disclose whether this is strictly read-only, what the response contains, or how results are ordered/paginated, leaving the behavior somewhat opaque.

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 sentences with no filler, the core action and scope are front-loaded in the first sentence, and the second sentence adds relevant downstream context. Every word 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 simple tool with one optional parameter and no required inputs, the description plus the schema is sufficient for an agent to select and invoke it correctly. It would be more complete with response-shape or pagination hints, but those are not essential for invocation.

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 there is only one parameter, so the schema already documents notebookId including its optionality. The description's 'optionally scoped to a single notebook by ID' mirrors the schema rather than adding new semantic detail, so it earns the baseline.

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 uses a specific verb and resource ('Lists OneNote sections') and notes optional notebook scoping, so an agent knows exactly what the tool acts on. It does not explicitly distinguish from sibling list tools like list_section_groups or list_pages, so it stops short of a 5.

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?

It provides a clear downstream use case ('Section IDs are needed by create_page') and notes the optional scope, giving an agent a concrete reason to call it. It does not name alternatives or exclusion conditions, so it is clear context without explicit when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add useful behavior about default format and markdown conversion, but it does not explicitly state that the operation is non-destructive or mention potential errors or auth requirements. Since the name and 'Returns' imply a read, this is adequate but not rich.

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 a single, front-loaded sentence that states the core action first and then adds the format variation. There is no fluff or redundancy; every word 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?

There is no output schema, so the description should explain what the agent can expect from the return value. It says 'full content and metadata' but does not detail the structure, included metadata fields, or any potential pagination/limits. This is a moderate gap for a tool that returns complex page data.

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 coverage is 100% and the schema already describes both parameters, including the enum descriptions for format (default HTML, markdown conversion). The description largely repeats this information without adding new meaning, so it meets the baseline but does not exceed it.

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 states a specific verb ('Returns') and a clear resource ('full content and metadata for a single OneNote page'). It distinguishes from list/search siblings by specifying 'single' page, making it clear this is for fetching one page's full data rather than lists or searches.

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 implies usage for reading a page's content, but it does not explicitly contrast with alternatives like resolve_page or search_pages, nor does it specify when not to use it. There is no mention of prerequisites or context, so an agent must infer when this tool is appropriate.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals that resolution is served from a local index, that verification happens against Graph on a miss, and that the index is repaired as a side effect. This is meaningful beyond the tool name, though it does not detail return shape or failure behavior.

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?

Three sentences cover the core transformation, the recommended usage context, and the stale-ID maintenance behavior. The most important information is front-loaded with a concrete example, and every sentence 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 resolver tool with no required parameters and no output schema, the description gives enough operational context: what it does, when to use it, and how it keeps the index fresh. It does not explain all possible combinations of optional parameters or error outcomes, but those are not critical for selecting and invoking the tool.

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 coverage is 100%, so the baseline is 3. The description adds value by showing that 'title' can be a free-form human description such as '今日任务 / 香港' rather than only an exact title, and it reinforces that section and notebook disambiguate duplicates. This goes beyond the schema's terse field descriptions.

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 states a precise verb and resource: it 'Turns a human description of a page... into a real page ID'. It also distinguishes itself from siblings like search_pages by emphasizing local-index resolution and Graph verification, so an agent can tell what this tool uniquely does.

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 gives explicit when-to-use guidance: 'Use this before reading or editing a page you named rather than identified.' It explains why stored IDs go stale and how resolution works on a miss, but it does not explicitly name alternative tools or state when not to use it, so it stops short of a full when/when-not formulation.

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

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

With no annotations, the description carries the full burden. It discloses the return structure (IDs, titles, parent info) but does not mention pagination behavior, sorting, scope (e.g., across all notebooks vs. a specific one), or error handling for no matches. The lack of side effects is implied by 'Searches' but not explicitly confirmed. It provides some transparency but leaves important behavioral details unstated.

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 a single sentence with no filler. It front-loads the core action and result, and every word earns its place. It is appropriately concise for a simple search tool.

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?

The tool is simple (2 params, no output schema), but the description omits the search scope (global across all notebooks vs. within a specific notebook) and any ordering or pagination details. The presence of a sibling find_pages suggests a need for differentiation, which is absent. It covers the basics but leaves key contextual gaps.

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%: both 'query' and 'limit' are described in the input schema. The description adds no extra meaning beyond the schema, so the baseline score of 3 applies. It neither clarifies nor adds to the parameter definitions.

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 uses a specific verb ('Searches') and resource ('OneNote pages') with a clear method ('full-text query'). It also states the return fields (IDs, titles, parent section/notebook info), which distinguishes it from list_pages or find_pages. The purpose is unambiguous and specific.

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 gives no guidance on when to use this tool versus alternatives like find_pages or list_pages. It does not mention any exclusions or conditions that would route an agent to a different sibling. The intended usage is implied (full-text search) but no explicit comparison is provided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation risk is known. The description adds context about the edit types and target selectors, but does not disclose potential side effects (e.g., what happens if an operation fails midway, whether edits are atomic, or impact on child elements). Since annotations cover the basic destructive nature, the description adds some but not rich behavioral insight.

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 a single, information-dense sentence. It front-loads the verb and action list, then provides essential targeting guidance with a pointer to read_page. No filler or redundant phrasing; 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?

Given the complexity of the operations array and the mutation nature, the description is adequate. It tells agents what it does and how to target correctly (via read_page). The schema covers parameter details and ordering, and annotations cover destructive semantics. The only missing piece is a note on return behavior or error handling, but that's not essential for invoking the tool correctly.

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 coverage is 100% with detailed descriptions for each parameter. The description goes beyond the schema by explaining that targets can be body, title, or data-id selectors and directs users to read_page for finding data-id values. This extra context helps agents correctly construct the `operations` parameter, which is complex (array of objects). The description adds meaningful value 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?

The description states a clear verb ('applies edits'), a specific resource ('an existing OneNote page'), and enumerates the edit operations (append, prepend, insert, replace, delete). It specifies the target kinds (body, title, data-id) and references read_page for obtaining data-id values. This distinguishes it from create_page (creating) and delete_page (removing the page entirely).

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 implies a workflow by telling users to find data-id values in read_page's HTML, which suggests the tool is used after reading a page. However, it does not explicitly state when to use this tool instead of create_page or delete_page, nor does it mention alternative tools. The absence of explicit exclusions leaves some ambiguity, but the context is clear enough for most agents to infer the right usage.

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