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

Beyond the annotations (which only indicate readOnlyHint=false and destructiveHint=false), the description adds important behavioral details: appending as a new outline block, newlines becoming separate paragraphs, and the guarantee that existing content is never overwritten. This is exactly the kind of context that helps an agent predict side effects.

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 concise sentences front-load the core action and then add two valuable details (newline handling and no-overwrite guarantee). Every sentence earns its place with no redundancy.

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 tool's simplicity (2 required params, no output schema), the description fully covers the essential behavior, safety characteristics, and content formatting. It is sufficient for an agent to select and invoke 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?

The schema already provides 100% coverage of both parameters, so the baseline is 3. However, the description adds semantics for the 'text' parameter by explaining how newlines are handled, which is not in the schema. This extra context raises the score.

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 ('Append text to the end of an existing OneNote page') with a specific resource (existing page) and output behavior (new outline block). This distinctly differentiates it from sibling tools like update_page or create_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 provides clear context that the tool appends text and never overwrites, which implies using it when adding content to an existing page without altering existing content. However, it does not explicitly name alternatives or state when not to use it, so it falls short of 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?

The description discloses the important default behavior (preview_only true) and the condition for actual creation. This goes beyond the annotations, which only state readOnlyHint=false. No contradiction with annotations.

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, front-loaded with the action, and includes the critical caveat without unnecessary words. Every part 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?

The description adequately covers the tool's purpose, the preview/approval workflow, and sets expectations for the default mode. It lacks details on return values or non-critical parameters, but overall it is complete enough for an agent to use correctly given sibling context and 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?

Only preview_only receives additional meaning in the description (its default and approval requirement). With schema description coverage at 20%, the description fails to explain section_id, title, date, or the template enum values. This is insufficient for low coverage.

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 'Create a page from a trusted template after preview', which is a specific verb+resource with a qualifier. It distinguishes this tool from onenote_create_page (no template) and onenote_template_preview (preview only).

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 the preview-then-approve workflow: 'preview_only defaults true; set false only after the user approves the rendered content.' This tells the agent when to create vs preview, though it does not explicitly name alternative tools.

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 only indicate readOnlyHint=false, which matches the 'Create' action. The description adds useful behavioral context: default creation in OneNote's default notebook folder, the ability to override with an absolute 'path', and the return of a notebook_id. This goes beyond the basic mutation signal from annotations.

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 three concise sentences with a clear front-loaded action ('Create a new notebook'). Every sentence adds value: default behavior, path override, and return value. No redundant or filler content.

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 that there is no output schema, the description appropriately mentions it returns notebook_id. It also clarifies the creation location and override behavior. It does not cover error cases or prerequisites, but for a straightforward creation tool, the essential context is adequately covered.

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 schema already describes both 'name' and 'path', but the description adds meaningful detail about the default folder location and requires the path to be absolute. This enriches the understanding of the 'path' parameter beyond the schema description alone.

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 'Create a new notebook,' which is a specific verb+resource pairing. It distinguishes the tool from sibling tools like onenote_create_section or onenote_create_page by focusing solely on notebook creation.

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 creating notebooks and provides guidance on how to use the 'path' parameter (absolute folder override), but it does not explicitly mention when not to use this tool or suggest alternative tools for other creation tasks. The usage context is clear but not fully elaborated.

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 indicate readOnlyHint=false and destructiveHint=false, which are consistent with the description's claim of creating a new page. The description adds that title and body are optional, but it does not disclose additional behavioral context such as permissions, return values, or side effects beyond what annotations already convey.

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 waste. The first sentence states the core purpose, and the second provides a helpful cross-reference for obtaining the required section ID. The description is well-structured and front-loaded.

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 description includes the essential prerequisite for the required parameter (how to get section_id) and covers the main purpose. Given the tool's simplicity and lack of output schema, it is sufficiently complete for invocation, though it could optionally mention what is returned upon creation.

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% since all three parameters have descriptions. The tool description mentions title and body text but does not add meaning beyond the schema's per-parameter descriptions, 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 clearly states the action (create), resource (page), and location (section). It distinguishes from sibling tools like onenote_create_section or onenote_create_notebook by specifying the page type and the section target.

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 the tool is used to create a page in a section and instructs the user to obtain the section ID from onenote_hierarchy. However, it does not explicitly mention when to use this tool versus alternatives like onenote_append_page or onenote_update_page, nor any exclusions.

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 state readOnlyHint=false and destructiveHint=false, so the mutation is disclosed. The description adds value by explicitly saying 'Returns the new section_id' and pointing to the ID source, which are useful behavioral details beyond the annotations.

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 clear sentences convey purpose, a prerequisite, and the return value with no unnecessary words. This is appropriately sized and front-loaded.

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 full schema coverage and annotations, the description is complete: it states what to create, where, where to get the ID, and what the tool returns. No critical information 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?

Schema description coverage is 100%, so the schema already explains both parameters well. The description adds only a small hint about getting IDs from onenote_hierarchy, which is helpful but not substantial enough to push beyond the baseline of 3.

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 ('Create') and identifies the resource ('new section in a notebook (or inside a section group)'). It clearly distinguishes itself from sibling tools like onenote_create_section_group and onenote_create_notebook by targeting sections specifically.

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: it can create inside a notebook or section group, and it tells the user to get the ID from onenote_hierarchy. However, it does not explicitly mention alternatives or when not to use it, so it falls short of 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?

Annotations already indicate a non-read-only, non-destructive operation. The description adds value by disclosing that the tool returns a section_group_id and that it can be nested inside another section group, providing useful behavioral context beyond the annotations.

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 concise sentences with no wasted words. It front-loads the action and includes the key return value, making it easy to parse quickly.

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 create tool with two required parameters and no output schema, the description sufficiently explains the operation, the accepted parent types, and the return value. Combined with annotations and schema, 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 provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description does not add significant new parameter semantics beyond the schema; it only reinforces that parent_id can be a notebook or another section group, which the schema already states.

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 section group and specifies the location ('inside a notebook or another section group'), distinguishing it from sibling tools like create_section and create_notebook. The verb 'Create' and resource 'section group' are specific and unambiguous.

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 the tool by focusing on section group creation and the nesting options. It provides clear context, though it does not explicitly mention alternatives or exclusions. The sibling list reinforces the distinct purpose.

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?

Goes well beyond the destructiveHint annotation by disclosing that the operation is highly destructive, requires user confirmation, is recoverable via recycle bin by default, and that permanent:true erases permanently. This is rich context directly relevant to a dangerous operation.

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 action and severity, then the key safety and recovery details. 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?

Covers all critical facets for a destructive delete: user confirmation, default recovery, permanent override, and the required ID. Given no output schema and good annotations, this description is complete and self-sufficient.

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 additionally explains the effect of permanent:true ('erases'), extending the schema's 'Erase permanently' with behavioral context, and clarifies recovery default. This adds value beyond the schema–hence a 4.

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 clearly 'Delete/close a whole notebook' with a specific verb and resource, distinct from sibling delete_page/delete_section tools. The additional warning 'Highly destructive' reinforces the action's scope.

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 explicit instruction to confirm the notebook ID with the user, and clarifies recoverable vs permanent behavior, which guides when to use the permanent flag. However, it doesn't mention alternatives or when to avoid this tool in favor of sibling tools.

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, so the description adds valuable context beyond that: default recycle-bin behavior, the permanent flag option, and the reminder to confirm the page ID. This gives the agent a fuller safety picture than the annotation alone.

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 with no fluff. The first sentence states the core action, the second covers the key nuance (permanent vs. default), and the third adds the safety warning. 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?

Given the simple two-parameter nature and the destructive annotation, the description covers essential behavior, defaults, and safety. Since there is no output schema, it does not explain the return value, but for a deletion tool this is a minor omission.

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 schema already covers both parameters at 100%, but the description adds meaning by explaining the default behavior (recycle bin) and clarifying the 'permanent' flag's effect ('erase it outright'). This supplements the schema definitions rather than repeating them.

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 ('Delete a OneNote page by its object ID'), clearly distinguishing it from sibling tools like onenote_delete_section and onenote_delete_notebook. The scope is unambiguous.

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 practical guidance: confirms the page ID source (from onenote_hierarchy or onenote_search) and explicitly states the one-page-per-call behavior. It doesn't list alternative tools for non-destructive actions, but the emphasis on correct ID use is enough for safe invocation.

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 destructiveHint annotation, the description discloses that the section is moved to the recycle bin by default (recoverable), can be permanently erased with permanent:true, and that the entire section including all pages is deleted. This adds valuable behavioral detail.

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 concise sentences, front-loaded with the action, covering all necessary details without 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?

For a simple destructive tool with 100% schema coverage, the description fully covers the behavior, the effect on pages, the safety warning, and the permanent option. No output schema is needed, and nothing 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 already documents both parameters fully (section_id required, permanent boolean with default false). The description adds slight context (permanent:true erases, recycle bin default) but does not significantly go beyond the schema, so 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 'Delete a section' with a specific verb and resource, and further clarifies that it deletes the entire section and all its pages, distinguishing it from sibling tools like delete_page or delete_notebook.

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 usage context: it is destructive, requires confirming the section ID, and explains the default recycle bin behavior with the permanent option. It does not explicitly name alternatives, but the context is sufficient for an agent to know when 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?

Annotations already indicate the operation is not read-only and not destructive. The description adds that it writes to a file and lists supported formats, but does not disclose potential behaviors like overwriting existing files or permission requirements. 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 brief, but the second and third sentences largely repeat schema-provided details, making them somewhat redundant. Still, it is front-loaded with the core purpose and remains appropriately sized.

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?

With no output schema, the description should indicate what the tool returns or how success/failure is communicated. It omits any mention of the operation's result or potential errors, leaving a notable gap for an agent to understand the full 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?

The input schema provides complete descriptions for all three parameters, including the format enum and target_path meaning. The description merely repeats this information without adding new semantic context, so it meets the baseline for high schema coverage.

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 identifies the tool's function: exporting a page or section to a file. This verb+resource+destination structure distinguishes it from sibling tools like onenote_get_page or onenote_create_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 the tool is for creating external file copies of OneNote content, but it does not explicitly differentiate when to use this versus alternatives such as onenote_get_page for retrieving content. There is no mention of when not to use it, so guidance is left implicit.

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 readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. The description adds the scope of extraction (specific insight categories) but does not disclose potential return formats, performance characteristics, or edge cases. This is comparable to the get_calls example where the description adds some context beyond annotations but not rich behavioral detail.

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 lists the extracted items and the scope. Every word contributes meaning, with no redundancy or filler. It is 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?

The tool is simple with two optional parameters, full schema coverage, and clear annotations. The description covers the core purpose and scope. However, since there is no output schema, the description does not indicate the format of the extracted insights (e.g., grouped by page, flat list), which would improve completeness. Still, it is sufficient for an agent to select and invoke 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%, so both parameters (start_id, max_pages) are already described. The description mentions 'scoped set of OneNote pages', which aligns with start_id, but adds no syntax or format details beyond the schema. Baseline of 3 is appropriate when the schema handles parameter semantics.

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 'Extract' and lists precise content types (action items, owners, due dates, decisions, risks, blockers, open questions) from a scoped set of OneNote pages. This clearly distinguishes it from sibling tools like search, get_page, and export, which operate on raw content or navigation.

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 structured insights from pages) but does not explicitly contrast it with alternatives like onenote_search or onenote_knowledge_digest. There are no stated exclusions or alternative tool names, so usage guidance is only implicit 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?

Annotations already declare the tool as read-only and non-destructive, so the safety profile is covered. The description adds behavioral context beyond annotations by specifying that it returns 'title and text content (flattened from the page XML)', which informs the agent that the output is a simplified text representation, not raw XML. This is valuable and goes beyond what annotations provide.

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 one sentence plus a short supplementary sentence, both concise and front-loaded. It avoids unnecessary detail while delivering the core purpose, output, and ID-acquisition method. 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?

Given the tool's simplicity (one parameter, no output schema), the description is complete: it states what the tool does, what it returns (title and text content), and how to get the required page_id. It also benefits from annotations that cover safety. No critical information 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 schema already fully describes the page_id parameter (OneNote page object ID), so baseline is 3. The description adds meaning by explaining where to obtain the ID (from onenote_hierarchy or onenote_search), which helps the agent understand the expected format and source. It also implicitly indicates that the parameter is a required identifier, aligning with 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 clearly states the tool's function with a specific verb ('Read') and resource ('OneNote page'), and explicitly differentiates it from siblings by noting that page IDs are obtained from onenote_hierarchy or onenote_search. It also implies a read-only operation, distinguishing it from mutation tools like create/update/delete.

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: it is for reading a page's title and text content. It also directs users to get page IDs from onenote_hierarchy or onenote_search, which is useful guidance. However, it does not explicitly mention when not to use it (e.g., if the user needs full-fidelity content or images, onenote_export might be more appropriate), but this is a minor gap.

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 readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds behavioral context by listing what the audit produces (duplicate candidates, stale pages, etc.) and highlights 'explainable confidence scores,' which is useful beyond schema/annotations. It does not mention operational details like pagination or performance, but with annotations covering the read-only nature, this is acceptable.

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 lists all major audit categories without filler. Every phrase contributes to understanding the tool's scope. It is dense but not verbose, and there is no redundant restating of the tool name or obvious fluff.

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 an audit tool with no output schema, the description does a good job of enumerating the types of results (duplicate candidates, stale pages, etc.) and mentions the confidence-score feature. The optional parameters are well-covered by the schema. It could be slightly more complete by explicitly contrasting with extract_insights or weekly_review, but given the annotations and schema, it is sufficiently complete 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?

The input schema already provides 100% coverage with clear descriptions for all three parameters (start_id, max_pages, stale_days). The description adds minimal extra param meaning—only the phrase 'notebook or section' aligns with start_id, but it doesn't explain how max_pages or stale_days affect results. Baseline of 3 is appropriate given full schema coverage.

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 'Audit' and clearly states the resource ('a notebook or section') and the distinct audit categories (duplicate candidates, stale pages, untitled/empty pages, ownerless action items, organization recommendations). This distinguishes it from sibling tools like onenote_search or onenote_extract_insights by focusing on health assessment rather than general search or insight extraction.

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 use case—auditing a notebook or section for organizational hygiene—but does not explicitly say when to prefer this over alternatives like onenote_extract_insights, onenote_weekly_review, or onenote_search. There is no exclusionary language or direct comparison to siblings, so usage guidance is only implicit.

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 readOnlyHint=true and destructiveHint=false, so no safety warnings are needed. The description adds behavioral detail about how different scopes affect the output granularity (notebooks vs. sections vs. full tree with page IDs), which goes beyond annotation defaults.

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 main purpose, no filler. The first sentence states exactly what the tool does; the second sentence provides action-oriented guidance on parameter usage. Every phrase 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?

No output schema exists, so the description carries the burden of explaining returns. It covers what is returned (notebooks through pages with IDs) and the effect of the scope parameter. It omits pagination/ordering details, but for a simple listing tool with read-only annotations, this is adequate.

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% (both scope and start_id have descriptions). The description adds extra semantic value by explaining the practical use case for each scope (e.g., 'sections' to find IDs for page creation), which is not in the schema and helps the agent decide which parameter value to use.

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 ('List') and clearly defines the resource ('OneNote hierarchy') including the exact components (notebooks, section groups, sections, pages) with their IDs. This distinguishes it from sibling tools like onenote_search or onenote_get_page, which operate on specific items.

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 context for each scope value: 'notebooks' for quick overview, 'sections' for finding section IDs for page creation, 'pages' for the full tree. It does not explicitly compare to alternative tools (e.g., when to use search instead), but provides strong situational 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?

Beyond the annotations (readOnly=false, destructive=false), the description adds substantial behavioral context: how headings are rendered (sized bold text), that pre uses Consolas lines, that div is recursed, that multiple root elements are allowed, and the strict XML well-formedness requirement (self-closing void tags, matching open/close tags). It also explains that both html and image_path may be provided. This gives agents a clear understanding of the tool's constraints and rendering 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?

The description is dense but well-structured: it starts with the primary action, then lists supported blocks, inline elements, and requirements. Every sentence provides new information without redundancy. The length is justified by the complexity of the content format, and the use of lists makes it easy to scan. 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?

Given the tool's complexity and the absence of an output schema, the description covers the essential aspects: what inputs are accepted, how content is interpreted, and the XML constraint. It is sufficiently complete for an agent to invoke the tool correctly. Minor gaps include not specifying behavior when both html and image_path are provided simultaneously (though 'and/or' suggests both are possible), and not describing error behavior for malformed XML. Overall, it covers the core usage well.

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 each parameter has a brief description. However, the main description adds significant semantic value by enumerating supported block and inline elements (h1-h6, p, ul/ol, table, pre, blockquote, div, b, i, u, code, a, span) and the XML parsing requirement, which goes beyond the schema's simple descriptions. It also clarifies the relationship between html and image_path ('and/or'), adding practical guidance.

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: 'Append rich content to a page' with specific content types (XHTML fragment, image). It identifies the resource (page) and the action (append), and distinguishes itself from sibling tools like onenote_append_page by emphasizing rich content and supported HTML blocks.

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: use this tool when you need to append rich HTML content or an image to a page. It does not explicitly mention alternatives or exclusions, but the detailed list of supported blocks implies when this tool is appropriate compared to simpler append/update tools. Sibling names like onenote_append_page and onenote_update_page suggest basic updates, while this tool is specifically for rich content.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it is source-grounded and produces per-page key points plus specific item categories. This goes beyond the annotations. No contradictions.

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 purpose, then output specification. No filler or repetition. 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 read-only tool with no output schema, the description adequately covers the return format (per-page key points, action items, etc.) and the scope options. It does not explain mode differences, but the enum covers that. The safety cap on max_pages is in the schema. Overall complete for 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?

Schema description coverage is 67% (start_id and max_pages are described, mode only has an enum). The description doesn't add any parameter-level detail beyond what the schema provides. It indirectly clarifies start_id's role by listing scopes, but that's already implied. Meets baseline but doesn't elevate.

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 ('Build') and a clear resource ('source-grounded... digest'), and specifies the scope (page, section, notebook, all open notebooks). It also states the returned content types (key points, action items, decisions, risks, questions), which fully distinguishes it from sibling tools like search or hierarchy.

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 on when to use the tool: when a digest is needed across any of those scopes, for the client to synthesize. It doesn't explicitly name alternatives or exclusions, but the purpose is clear enough that an agent can infer when to invoke it. It lacks an explicit 'when not to use' statement, 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?

The description goes beyond the annotations by disclosing a critical side effect: the moved page gets a NEW object ID and the old ID becomes invalid. It also directs the agent to use the returned page_id for further operations, which is exactly the kind of behavioral context needed to avoid stale references.

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 long, front-loads the primary action, and uses the second sentence for the most important caveat. There is no redundant or vague wording.

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 two-parameter mutation tool with no output schema, the description covers the most important contextual element (ID invalidation) and mentions the returned page_id. It could also describe error conditions or the full response format, but the critical information is present.

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 schema already provides 100% coverage with clear descriptions for both page_id and target_section_id. The description adds no additional parameter-level detail, so it does not improve on the schema's 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 ('Move') and resource ('page') with a clear destination ('another section'), making the tool's function unambiguous. This distinguishes it from sibling tools like onenote_move_section (moves a section) and onenote_reorder_pages (reorders within a section).

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 states the action plainly but does not explicitly say when to use this tool instead of alternatives such as onenote_move_section or onenote_reorder_pages. The appropriate usage is implied by the tool name and first sentence, but there is no explicit when/when-not 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds minimal context about the destination constraint ('different') but does not disclose potential side effects like broken references or permanence of the move.

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, front-loads the action, and contains zero filler. Every word contributes to the meaning.

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 two-parameter tool with no output schema, the description adequately covers the core purpose and destination. It could mention how to obtain IDs (via hierarchy) or error cases, but these are not essential for understanding the 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% because both parameters have descriptions. The tool description adds only the word 'different' to emphasize that the target must be a different parent, which is a minor semantic addition beyond the schema's explicit 'Destination notebook or section group 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 clearly states the action ('Move') and the resource ('a section') with a specific destination ('into a different notebook or section group'). It distinguishes itself from sibling tools like onenote_move_page by targeting section-level moves and from onenote_reorder_sections by specifying a different parent.

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 the tool (when moving a section to a new parent) but does not explicitly mention alternatives or exclusions such as using onenote_reorder_sections for within-notebook reordering. It provides a clear context but no when-not 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?

The description discloses that the tool changes what the user sees on screen, which is a behavioral side effect beyond the annotations' readOnlyHint: false. This clarifies the nature of the mutation (UI navigation rather than data modification).

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 primary action in the first sentence and usage constraints in the second. 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, and the description covers the action, the target object types, the side effect, and the usage condition. No output schema is needed.

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 only parameter is object_id, and the description clarifies that it refers to a notebook, section, or page ID, adding meaning to the schema. Since schema coverage is 100%, this is a bonus.

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 opens notebooks, sections, or pages in the visible OneNote window, using the verb 'open' and listing the resource types. This distinguishes it from sibling tools that create, delete, or modify content.

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 explicitly states when to use it: 'use only when the user asked to open or show something.' This provides clear usage guidance, though it does not name alternative tools 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 already declare destructiveHint=true, and the description adds context by specifying it operates on an 'existing page' and sets its title, clarifying it does not move or delete the page. However, no further side effects or reversibility are discussed.

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 that directly states the purpose and includes a clarifying parenthetical. Every word earns its place, with no redundancy.

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 simplicity of the tool (2 required parameters, no output schema, and annotations indicating destructiveness), the description is mostly complete. It could mention error conditions or title uniqueness, but these are not essential for basic 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?

The input schema already provides descriptions for both parameters (page_id and new_title) at 100% coverage. The description adds no additional parameter meaning beyond what the schema 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 uses a specific verb 'Rename' with a clear resource 'page' and clarifies the action as setting its title. This distinguishes it from sibling tools like onenote_rename_section or onenote_move_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?

No guidance is provided on when to use this tool versus alternatives like onenote_update_page or onenote_append_page. There is no mention of exclusions or alternative scenarios.

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 readOnlyHint: false, indicating a mutating operation. The description adds no behavioral context beyond this—no mention of side effects, permissions, or what happens to linked content. It merely repeats the rename action implied by the annotations.

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 wasted words. It captures the essential purpose while leaving parameter details to the schema, which is ideal for a simple 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?

For a simple two-parameter rename operation with complete schema descriptions and clear annotations, the description is nearly sufficient. It could mention return values or error conditions, but no output schema exists and the operation's simplicity reduces the need for extensive context.

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% for both parameters (section_id, new_name), so the schema fully documents them. The description adds no additional parameter details, but given the high coverage, a 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 'Rename an existing section.' uses a specific verb (rename) and resource (section), clearly distinguishing it from sibling tools like onenote_rename_page and onenote_move_section. It directly states the tool's action without ambiguity.

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 implicitly indicates use when renaming a section, but it provides no explicit guidance on when to prefer this over alternatives or any exclusions. The sibling tools make the context somewhat clear, but no direct comparison or when-not-to-use info is given.

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 indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the key behavioral nuance that exactly one reference must be provided, which is useful context beyond the schema.

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 concise sentences that fully convey the core action and key usage constraint. No unnecessary words or repetition of schema details.

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 reorder operation with 4 parameters, the description covers the essential behavior and parameter usage. No output schema exists, but the return value is likely trivial; a mention of what happens if neither reference is provided would improve completeness but is not critical.

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 descriptions already exist for each parameter. The description adds semantic value by clarifying that before_page_id and after_page_id are mutually exclusive alternatives, which is not explicit in 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 clearly states the verb 'change page order' and the resource 'within a section', distinguishing it from sibling tools like onenote_move_page which likely moves between sections. The scope is specific and matches the tool 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?

It explicitly says to provide either before_page_id or after_page_id, giving clear placement guidance. It implies the tool is for reordering within a section, which differentiates it from moving across sections, though it does not explicitly name alternatives.

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 indicate this is a write operation (readOnlyHint=false). The description adds the scope of reordering within a notebook or section group, which is useful context, but it does not disclose behavior if both before_section_id and after_section_id are provided, or what happens if the section is not found. This is a moderate level of transparency beyond the annotations.

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, front-loaded with the purpose, and contains zero filler. Every word serves a clear function: stating the action, the scope, and the required reference parameter.

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 description covers the core operation, the parent context, and the reference parameter choice. It does not explain the response format (no output schema) or edge cases like both references provided, but given the tool's simplicity and the presence of annotations, it is reasonably complete. A small gap is the lack of explicit validation 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?

Schema coverage is 100%, with each parameter having a description. The description adds semantic value by stating 'Provide either before_section_id or after_section_id as the reference,' which clarifies the mutual exclusivity that is not explicitly in the schema. This goes beyond the baseline for high schema coverage.

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 ('Change section tab order') and the resource ('within a notebook or section group'). It distinguishes itself from siblings like onenote_reorder_pages (pages vs sections) and onenote_move_section (which moves sections, not reorders within the same parent).

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 direct usage guidance by explaining that either before_section_id or after_section_id must be supplied as the reference. It implies the tool is for reordering within a single parent, which differentiates from moving sections across parents, but it does not explicitly name alternatives or exclusions.

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 this as a read-only operation (readOnlyHint=true, destructiveHint=false), so the description has a lower burden. It adds that results include page IDs, but it does not disclose potential behaviors like result limits, ordering, or the effect of the optional start_id scope beyond what the schema already states.

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 short, direct sentences with no redundant wording. It efficiently conveys the core action and return value.

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?

With no output schema, the description explains that it returns matching pages with IDs, which is sufficient for basic use. However, it lacks details on result pagination, ordering, or whether the search spans all notebooks by default. Given the low complexity and strong schema/annotations, this 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?

Schema coverage is 100% with both 'query' and 'start_id' described. The description adds no extra meaning to the parameters, merely restating that it is a full-text search. This is acceptable but does not go 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 clearly states the tool performs full-text search across OneNote pages and returns matching page IDs. The verb 'search' and resource 'OneNote pages' are specific, but it does not explicitly differentiate from sibling tools like onenote_navigate or onenote_get_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 usage for finding pages by content but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusionary scenarios, leaving the agent to infer context from the tool name and siblings.

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 readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'without modifying OneNote.' It also adds the qualifier 'trusted' and enumerates available templates, providing context beyond the annotations. It does not explain behavior for the date parameter, but that is a minor gap given the annotations.

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 fluff. The core action is stated immediately, followed by the template list. 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?

The tool is simple (3 params, no output schema), and the description covers its main purpose and template options. However, it omits the role of 'title' and 'date' in the preview and what the preview output looks like. Given no output schema, the description should be more explicit about the return behavior to be fully 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?

Schema description coverage is 0%, so the description must explain parameters. It lists the enum values for 'template,' which is helpful, but 'title' and 'date' are left unexplained. 'Title' is fairly self-explanatory, but 'date' could mean the meeting date, creation date, or something else, and no syntax/format is provided. The description compensates for only a third of the parameters.

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 ('Preview') with a clear resource ('trusted page template') and explicitly states the non-mutating behavior ('without modifying OneNote'). It also lists the available templates, distinguishing it from sibling creation tools like onenote_create_from_template.

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 phrase 'without modifying OneNote' clearly signals this is for read-only previewing, which distinguishes it from create/edit tools. However, it does not explicitly name alternative tools or state 'use this when you only need to see the template,' so it falls short of explicit when/when-not 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?

The description discloses critical behavioral details beyond the annotations: 'replace' clears existing body outlines, 'append' adds to the end, the title is preserved, and newlines become separate paragraphs. This adds significant context to the destructiveHint=true annotation and helps the agent understand the tool's side effects.

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 three concise sentences, front-loaded with the main purpose. Each sentence provides useful information without redundancy or fluff, making it easy for an agent to parse quickly.

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 update tool with 3 parameters, the description is complete. It covers the main action, mode-specific behavior, title preservation, and content formatting. No output schema exists, but none is needed for this straightforward operation, and the description covers all necessary operational context.

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 baseline is 3. The description adds extra meaning beyond the schema: it explains the mode behavior in detail and notes that newlines in content become separate paragraphs, enriching the semantics for the 'content' and 'mode' parameters beyond their simple schema 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 clearly states the tool's function: 'Update a page's body content' with a specific verb and resource. It distinguishes itself from siblings by explaining the two modes, 'replace' and 'append', which differentiates it from onenote_append_page and other page tools.

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 context by explaining the default mode and the effect of each mode, but it does not explicitly mention alternatives or when not to use this tool. Given the sibling onenote_append_page exists, there is no explicit guidance on choosing between the two, leaving the usage context somewhat implicit.

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?

Given annotations already declare readOnlyHint=true and destructiveHint=false, the description adds value by explicitly confirming 'This is read-only and does not create a page.' This reassures the agent about side effects beyond the generic read-only hint, which is useful for a tool that might otherwise be assumed to create deliverables.

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, each earning its place. It front-loads the core purpose and immediately clarifies the read-only nature. No filler or redundant phrasing, making it compact and easy to parse.

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 aggregation tool with two optional parameters and no output schema, the description explains what it produces and confirms no side effects. It could mention the return format or how the source pack is structured, but the essential operational context is present given the annotations and 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?

The input schema covers both parameters (start_id and max_pages) with detailed descriptions and defaults, so schema coverage is 100%. The description does not add additional parameter-specific meaning, which aligns with the baseline 3 for high schema coverage where the description need not repeat schema details.

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 builds a weekly-review source pack from recent/scoped notes, naming the included content types (key points, decisions, risks, incomplete action items). This is a specific verb+resource combination that distinguishes it from sibling tools like onenote_search or onenote_get_page, though it does not explicitly name an alternative.

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 weekly-review use case and notes the tool is read-only, but it does not explicitly state when to prefer this tool over siblings such as onenote_extract_insights or onenote_knowledge_digest. There is no when-not-to-use guidance or named alternatives, so usage context 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.