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. 'Add' implies a mutation, but the description says nothing about side effects, required permissions, whether the page must be unpublished, or what happens on failure. It is only marginally more informative than a bare operation name.

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, but for a tool requiring five parameters and performing a page mutation, it is under-specified rather than appropriately concise. Structure is fine; substance is missing.

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?

Against a tool with five required parameters, no annotations, no output schema, and only 20% schema description coverage, the description is inadequate. It does not explain where the web part is placed (section/column), what the JSON must contain, or what success looks like.

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 only 20%, so the description must compensate for the four undocumented parameters (siteId, pageId, sectionIndex, columnIndex). The phrase 'from a JSON definition' loosely corresponds to webPartJson, but adds no guidance about the required IDs, index values, or expected JSON structure.

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: 'Add a custom web part from a JSON definition.' That is clear enough to distinguish it from sibling tools like add_image_webpart or add_text_webpart, which are type-specific. It does not explicitly name or contrast those siblings, so it falls 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?

No when-to-use guidance is provided. The word '(advanced)' hints at a use case but does not state when an agent should choose this tool over add_image_webpart, add_text_webpart, or other web-part insertion tools, nor does it mention prerequisites such as page edit permissions.

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 says nothing about permissions, insertion behavior, whether the divider is appended to a section/column, or what happens on failure, leaving a mutation tool completely 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?

The single sentence is technically concise and front-loaded, but for a 4-required-parameter tool it is under-specified rather than appropriately sized. It omits all necessary invocation details, so brevity here is a liability.

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 annotations, no output schema, and 0% parameter documentation leave the definition severely incomplete. An agent cannot determine where the divider goes, what identifiers are required, or what the call returns.

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% and the description does not mention any of the four required parameters (siteId, pageId, sectionIndex, columnIndex). For a 4-parameter tool with zero schema documentation, the description should compensate but adds no meaning at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add a horizontal divider'), which is clearer than a tautology. However, it offers no differentiation from the sibling 'add_spacer', which an agent could easily confuse with a divider in a page-building context.

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 on when to use this tool versus alternatives like add_spacer or add_section. The agent must infer placement context entirely from the schema, with no textual routing.

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 nothing: no creation vs modification semantics, no permission/auth needs, no effect on the page layout, no return value.

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?

Extremely short and front-loaded, but the brevity is under-specification rather than effective conciseness. The single sentence is efficient yet earns little because it omits critical context.

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?

A mutation tool with no annotations, no output schema, and 6 of 7 parameters undocumented. The description is completely inadequate for an agent to call this correctly, especially given the 5 required parameters and positional sectionIndex/columnIndex semantics.

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 14% – only imageUrl is annotated. The description says nothing about any of the 7 parameters, leaving siteId, pageId, sectionIndex, columnIndex, altText and caption undocumented in both schema and description. It should compensate for the low coverage but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (add) and resource (image web part), and names where it goes (a section). Distinguishable from the sibling add_text_webpart and add_custom_webpart by the web part type, though it doesn't differentiate from them beyond the noun.

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 when-to-use vs alternatives guidance. With siblings add_text_webpart and add_custom_webpart, an agent gets no signal about which web part to choose. Prerequisites (page must exist, section must exist) are absent.

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. 'Add' implies a mutation, but the description says nothing about required permissions, whether it overwrites existing links, ordering behavior, or what happens on failure.

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?

Single short sentence with no wasted words. It is front-loaded with the core action, though the parenthetical could be expanded to earn its place more fully.

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 5-parameter mutation tool with no annotations and no output schema, the description is too thin. It omits permission needs, side effects, and what the return might contain.

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 60%, with url, title, and isExternal documented but siteUrl and navType only partially. The description's mention of Quick Launch and Top Navigation hints at navType values but does not add meaning beyond what the enum already supplies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add a navigation link') and names the two navigation types it targets (Quick Launch, Top Navigation). Sibling tools like add_text_webpart, add_image_webpart, and remove_navigation_link are clearly distinct from this one.

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 on when to use this versus remove_navigation_link or get_navigation, and no prerequisites such as permissions or site connection requirements. The parenthetical naming of nav types is a hint about scope but not usage timing.

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 behavioral burden. 'Add a new section' minimally implies an additive, non-destructive mutation, but it says nothing about required permissions, whether the page must be unpublished or connected first, or how the new section is positioned relative to existing ones.

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 short sentence with no waste, but it is under-specified rather than genuinely concise — the brevity comes at the cost of missing context the agent needs.

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 mutation tool with 4 parameters, no annotations, no output schema, and half its parameters undocumented, the description is too thin. It should at minimum cover prerequisites and the sectionTemplate/emphasis options it accepts.

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 only 50%, and the description mentions no parameters at all. It does not explain siteId/pageId (undocumented in the schema) or add any meaning beyond the enum descriptions already present for sectionTemplate and emphasis, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource combination ('Add a new section to a page'), so the agent knows the operation and target. However, it offers no differentiation from sibling tools that also add page content (add_text_webpart, add_image_webpart, add_spacer, add_divider), leaving the section-vs-webpart distinction to inference.

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?

There is no guidance on when to use this tool versus the many sibling 'add_*' content tools, nor any stated prerequisites such as needing an existing page or site. Usage is only implied by the name.

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 behavioral burden. It says nothing about permissions, whether it requires a publish step, whether existing layout is affected, or what is returned. For a mutation tool with zero annotation coverage this is a significant gap.

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 short sentence with no waste, but it is under-specified rather than efficiently concise. There is no front-loaded context about placement or prerequisites.

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 five params, four required and 80% undocumented, no annotations, and no output schema, the description is far too thin to support correct invocation. An agent would not know where the spacer lands or what state changes occur.

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 only 20%: height has a default documented, but siteId, pageId, sectionIndex and columnIndex are bare. The description adds no parameter meaning, leaving four required params effectively undocumented.

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 ('add' + 'spacer web part'), which is clear on its own. However, it does not differentiate from close siblings like add_divider or add_text_webpart, which also add visual elements to a page, so the agent must infer the distinction.

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 given about when to use this tool versus alternatives such as add_divider or add_section, nor any prerequisites like requiring an existing page or section. The agent gets no routing signal beyond the name.

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 behavioral burden, and it discloses almost nothing. It doesn't say whether the target section/column must already exist, whether the page must be republished afterward, what permissions are required, or what happens on failure for a mutating 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?

A single short, front-loaded sentence with no wasted words. It is efficient, though its brevity edges toward under-specification rather than crispness.

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 5-parameter mutating tool with no annotations and no output schema, the description omits prerequisites, return behavior, and side effects. An agent would need to open the schema and guess at the surrounding workflow (e.g., that a section must exist and the page may need publishing).

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 60%: html, columnIndex, and sectionIndex are documented in the schema, while siteId and pageId are undocumented everywhere. The description adds no parameter meaning at all beyond the vague phrase 'to a section', so it fails to compensate for the coverage gap.

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 verb and resource ('Add a text web part') but is largely a restatement of the tool name, with only '(HTML)' and 'to a section' adding anything. It implies differentiation from siblings like add_image_webpart or add_custom_webpart by resource type, but never makes that contrast explicit.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as add_custom_webpart for non-HTML content or add_image_webpart. The agent must infer from the name alone that this is for text/HTML 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?

No annotations are present, so the description carries the burden. It discloses useful behavior ('Automatically discovers the tenant and resolves the site'), which is real value beyond the name. However it says nothing about what 'connecting' statefully entails, auth requirements, or side effects relative to the disconnect sibling.

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 and followed by the resolution behavior and the usage trigger. No wasted text.

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 connection tool with no annotations and no output schema, the description covers purpose, automatic tenant discovery, and when to use it. It lacks any note on auth or connection lifecycle, but is otherwise complete for the call itself.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single url parameter is fully documented with format and an example, so the schema already does the work. The description adds only that the URL implicitly determines the tenant, which is marginal. Baseline 3 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?

States a specific verb ('Connect to') and resource ('SharePoint site from its URL'), and distinguishes itself from the sibling get_site_by_url by emphasizing the connection/starting-point role rather than a pure lookup.

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 'Use this as the starting point when a user provides a SharePoint URL,' giving clear context for invocation. No exclusions or named alternatives against get_site_by_url or search_sites, so it stops 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?

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It does not disclose whether the page is created as a draft vs. published (autoPublish exists but its default is unstated), what permissions are needed, whether the operation is reversible, or what the call returns.

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 with no filler, stating the action and the optional configurability up front. It is efficient, though arguably under-sized for a seven-parameter mutation 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 seven-parameter write tool with no annotations and no output schema, the description is far too thin. It omits prerequisites, publish behavior, and return/result information, leaving gaps that neither annotations nor an output schema can fill.

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 86%, so the schema already documents most parameters including the layout and titleLayout enums. The description only echoes 'layout and title area template' and adds no syntax, defaults, or format detail beyond the structured fields, so the baseline of 3 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 states a specific verb and resource ('Create a new SharePoint page') and hints at scope with 'optional layout and title area template'. It is clearly distinguishable from get_page, update_page, delete_page, and publish_page, but it never explicitly names those siblings to reinforce the boundary.

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?

There is no when-to-use guidance, no mention of prerequisites (e.g. connecting to a site first, or that siteId is required), and no comparison to update_page or publish_page. The agent must infer usage entirely from the name.

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, and it says nothing. For a destructive operation it fails to state whether deletion is permanent or recoverable, whether it requires ownership/admin permissions, or what happens to a page's sections and webparts.

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?

It is short and front-loaded, but this is under-specification rather than conciseness — the single sentence conveys essentially nothing beyond the tool name.

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 annotations, no output schema, and 0% parameter documentation, the description needs to do substantial work and does none of it. An agent cannot safely call a destructive two-parameter tool on this basis.

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% and the description adds no meaning for siteId or pageId. Both are undocumented strings, leaving the agent with no guidance on identifier format or how to resolve 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 restates the tool name almost verbatim ('Delete a page' for delete_page) with no additional specificity about scope, target, or effect. It does convey verb+resource, so it is not entirely meaningless, but it offers no differentiation from siblings like update_page, publish_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?

There is no guidance on when to use this tool versus alternatives such as update_page or publish_page, nor any note about prerequisites, permissions, or irreversibility. The agent is left to infer everything from the name alone.

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 burden and discloses the key behavioral trait that it clears cached authentication. It doesn't mention session/account impacts beyond the cache, but this is a solid disclosure for a zero-parameter 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 core action and followed by the use case. 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?

For a simple, parameterless tool with no output schema, the description provides enough context to call it correctly. It could mention that subsequent operations require re-authentication, but the implied effect of clearing cached auth is 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?

The tool takes no parameters, so the schema already provides full coverage. The description adds no parameter information, which is appropriate; baseline is 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Disconnect') and resource ('SharePoint') along with the side effect of clearing cached authentication. This clearly distinguishes it from siblings like connect_to_site and leaves no ambiguity about its function.

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 to use it to switch accounts or re-authenticate, which gives a clear context for invocation. It does not name alternatives or when-not-to-use scenarios, but for a simple disconnect tool no alternative 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 must carry the burden. It discloses that it retrieves templates, implying a read-only operation, but does not state whether it requires permissions, has rate limits, or returns a static list. The behavior is partially 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 a single, front-loaded sentence that efficiently states what the tool does without any 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 is a simple getter with no parameters and no output schema, the description is minimally complete. However, it does not describe the return format or whether templates are filtered by context, which might be helpful for an agent.

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, and the schema coverage is 100% (though empty). The baseline for zero parameters is 4, and the description does not add parameter information, but none is needed.

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 gets design templates and specifies the scope (sections, title areas, web parts), distinguishing it from sibling tools that add or manipulate web parts. However, it does not differentiate from other potential 'get' tools, though no similar getter exists in the sibling list.

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 when needing design options for layout elements, but does not explicitly state when to use this versus alternatives or when not to use it. The context is somewhat inferable from the 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a read operation, but the description does not state permission requirements, authentication needs, return format, or whether any side effects occur. This is a significant gap for a tool with zero annotation coverage.

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 wasted words and is front-loaded with the core action and resource. It is appropriately sized for a simple two-parameter read 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 relatively simple with two fully schema-documented parameters, but the absence of annotations and an output schema means the description should do more to explain what the return value contains and any access constraints. It provides the minimum viable information but leaves clear 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%, so the schema already documents both parameters. The description adds value by mapping the enum values 'quick' and 'top' to the human-readable labels 'Quick Launch' and 'Top Navigation', clarifying the meaning of the navType parameter beyond the schema's 'Navigation type' description.

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: 'Get site navigation'. It distinguishes the tool from sibling write operations like add_navigation_link and remove_navigation_link by using 'Get', but it does not explicitly differentiate from other read tools such as get_page or get_site_details.

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, no prerequisites, and no exclusions. The parenthetical '(Quick Launch or Top Navigation)' clarifies the navType parameter but does not address usage context.

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. 'Get' implies a non-mutating read and the description usefully discloses the payload composition (canvas layout, web parts), but it says nothing about permissions, error behavior for missing pages, or payload size/cost.

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 with no filler; the resource and the returned content scope are stated immediately. 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?

With no output schema, the description takes on the return-value burden and does so adequately ('full content ... canvas layout and web parts'). However, it leaves the siteId parameter entirely unexplained and gives no hint about what 'full content' contains structurally, so an agent lacks enough to call it confidently in ambiguous cases.

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 50%: pageId has an uninformative 'Page ID' description and siteId has none at all. The description adds nothing about either parameter, such as ID formats, where to obtain siteId, or whether pageId is site-scoped, so it does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get the full content of a page') and scopes the return payload with 'including canvas layout and web parts'. This meaningfully separates it from list_pages and implies a contrast with get_page_layout, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives like list_pages or get_page_layout, nor any prerequisites (e.g., that a site must be connected first via connect_to_site). The agent must infer usage entirely from the name and sibling list.

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 identifies the tool as a read operation ('Get'), but does not disclose whether it requires authentication, any rate limits, the return format, or what 'layout' includes. For a read tool with no annotations, more transparency would help.

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?

One concise sentence that front-loads the core action and resource, with a clarifying parenthetical. No wasted words. Perfectly sized for this 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 two-parameter read tool with no annotations and no output schema, the description is too sparse. It omits parameter explanations and any behavioral context. An agent would need to guess the meaning of siteId and pageId and what the return structure contains.

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 schema gives no parameter documentation. The description does not mention siteId or pageId at all, leaving both required parameters completely undefined. With two undocumented parameters, the description fails to compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource: 'Get the canvas layout of a page'. The parenthetical '(sections, columns, web parts)' adds detail about what layout means. It doesn't explicitly contrast with siblings like get_page, but the specific subject 'layout' distinguishes it from the get_page metadata 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?

No indication of when to use this tool versus get_page, list_pages, or other read tools. No prerequisites or context given. The agent must infer that this is for retrieving structural layout information, but the description offers no guidance on appropriate 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?

No annotations are provided, so the description carries the full behavioral burden, and it says nothing about permissions, behavior when the site is not found, or what is returned. Only the minimal lookup semantics are conveyed.

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 short sentence with the key concept front-loaded and no wasted words. It is terse to the point of omitting useful context, but structurally clean.

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 annotations and no output schema, the description is the only place to explain return shape, permission needs, and not-found behavior, and it covers none of these. For a lookup tool this is under-specified rather than 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% and each property carries an example ('contoso.sharepoint.com', 'sites/marketing'), so the schema does the heavy lifting. The description restates the two parameters without adding format or normalization guidance, matching the baseline 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?

States a clear verb+resource ('Find a site') with the lookup key (hostname and path), which distinguishes it from listing tools like list_my_sites or search_sites. It does not, however, distinguish itself explicitly from get_site_details, which an agent must infer.

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 when-to-use guidance and no mention of alternatives such as search_sites (for querying by name) or get_site_details. The agent must infer that this is for resolving a known URL to a site.

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 behavioral burden. 'Get' implies a read-only operation and the field list signals the return shape, but there is no disclosure of permissions needed, error behavior when a siteId is invalid, or response format. Adequate but thin for an unannotated tool.

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?

One efficient sentence, front-loaded with the verb and resource, with the returned-field parenthetical earning its space since there is no output schema. No waste or 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?

For a single-parameter read tool with a fully documented schema, the description covers purpose and previews the return payload, which compensates for the absent output schema. Missing only usage routing against sibling lookup tools.

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% — the siteId parameter documents its format ('contoso.sharepoint.com,guid,guid'). The description adds no additional parameter meaning, so the baseline 3 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?

States a specific verb ('Get') and resource ('details of a SharePoint site') and enumerates the returned fields (ID, URL, description, lists), so an agent knows exactly what it retrieves. It does not distinguish itself from near-siblings like get_site_by_url, search_sites, or list_my_sites, which is the only thing keeping it off 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?

The description gives no indication of when to prefer this tool over get_site_by_url, search_sites, or list_my_sites, nor any prerequisite (e.g. resolving a siteId from search_sites first). Usage is only implied by the name, with no exclusions or alternative routing.

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 conveys that this is a read operation implicitly, but says nothing about permissions required, result ordering, pagination, or what happens when the user follows nothing.

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 with no filler. It is appropriately sized for a no-argument list tool, though it is on the sparse side given the available space.

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 zero-parameter list tool this is largely adequate, but with no output schema and no annotations the description should say at least what a returned site entry contains or how many are returned. The gap is minor but real.

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 takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond the fact that no filtering or paging inputs are accepted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('SharePoint sites the current user follows'), which is a precise scope. It is distinguishable from search_sites and get_site_details by the 'followed by current user' qualifier, though it doesn't explicitly name those siblings.

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 on when to use this versus search_sites or get_site_details, all of which could plausibly surface sites. The 'follows' scoping implies a use case but the agent must infer that this returns only followed sites rather than all accessible sites.

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 behavioral burden, yet it discloses nothing about pagination, result limits, ordering, permission requirements, or whether unpublished/draft pages are included. 'List all' even implies an unbounded result set without any caveat about paging.

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 with zero filler, which is efficient. It is arguably too terse for the information an agent needs, but it commits no structural waste.

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 listing tool with no output schema and no annotations, the description should at least hint at pagination behavior or what a page record contains. As written, an agent knows what it does but little about what it gets back or when it is the right 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?

Schema description coverage is 0% for the single required siteId, so the description must compensate. It only implies that siteId identifies the SharePoint site whose pages are listed, offering no guidance on ID format or how to obtain a valid siteId (e.g., via get_site_by_url or list_my_sites).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all pages of a SharePoint site'), which is clearly distinct from the singular get_page or the mutating create_page/update_page siblings by implication of 'all'. However, it never explicitly names an alternative or clarifies the boundary with get_page, so it stays at 4 rather than 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?

There is no when-to-use guidance, no prerequisites, and no mention of when a caller should prefer get_page or search_sites instead. The agent must infer the use case entirely from the verb.

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 behavioral burden, and it delivers almost nothing. It does not disclose whether publishing is reversible, whether it requires prior draft/unpublished state, what permissions are needed, or what happens to the live site content afterward.

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 three-word description is front-loaded and free of waste, but its brevity reflects under-specification rather than conciseness. For a mutation tool with two required parameters, this is far too little text to 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?

With no annotations, no output schema, no parameter descriptions, and two required undocumented inputs, the definition is inadequate for an agent to call this mutation correctly. Nothing about preconditions, side effects, or return behavior is 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?

Schema description coverage is 0% for both required parameters (siteId, pageId), and the description adds no information about them. It does not explain whether these are IDs versus names, what format they take, or where to obtain them, leaving both required inputs entirely opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Publish') and resource ('page'), which is a recognizable state transition rather than a tautology. However, it does not differentiate itself from siblings like update_page, create_page, or delete_page, which also mutate a page, so an agent must guess how 'publish' differs from a general update.

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?

There is no guidance on when to use this tool versus update_page or create_page, no prerequisites (e.g., the page must exist as a draft), and no mention of alternatives. The agent only has the bare verb to infer intent from.

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. 'Remove' implies a destructive mutation, but it does not explain permissions needed, reversibility, side effects on navigation, or what happens to the linked node. This is a significant gap for a deletion 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?

The description is a single very short sentence that is front-loaded but severely under-specified. It does not provide enough information to justify its brevity. Every sentence should earn its place, and this one fails to convey necessary distinctions or constraints.

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 destructive tool with three required parameters, no annotations, no output schema, and low schema description coverage, the description is wholly inadequate. It omits prerequisites, parameter explanations, side effects, and any routing to sibling tools. An agent cannot reliably invoke this tool based on the definition.

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 low at 33%: only nodeId has a description, navType has an enum but no explanation of 'quick' vs 'top', and siteUrl is undocumented. The description adds no parameter meaning whatsoever, failing to compensate for the schema gap. It does not explain what a navigation node ID is or how to obtain one.

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 'Remove a navigation link' restates the tool name almost verbatim. While it names a specific verb and resource, it provides no scope, no distinguishing detail, and no differentiation from siblings like add_navigation_link or get_navigation. This is essentially 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?

There is no guidance on when to use this tool versus add_navigation_link, get_navigation, or any other sibling. No prerequisites, conditions, or exclusions are stated. The description offers no usage context beyond the obvious verb.

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 does not state that this is a read-only operation, what permissions are required, whether results are paginated or ranked, or any scope limits. Only the terse purpose is conveyed.

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 efficient phrase with no filler. It is appropriately short for a one-parameter tool, though it is too sparse to be front-loaded with any routing or behavioral context.

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 search with no output schema, the description covers the essentials, but it omits any differentiation from list_my_sites and get_site_by_url, leaving the agent to guess which site-retrieval tool fits a given request.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single query parameter is fully documented in the schema. The description's "by keyword" adds nothing beyond the schema's "Search term for sites," so the baseline 3 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?

"Search for SharePoint sites by keyword" states a clear verb (search) and resource (SharePoint sites) plus the matching mechanism. However, it does not differentiate from the sibling list_my_sites, which an agent could easily confuse it with.

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 when-to-use guidance, no prerequisites, and no mention of the alternative list_my_sites despite it being a plausible competitor. The agent must infer that this is for keyword-driven discovery rather than enumerating known sites.

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 behavioral burden. It implies a mutation but does not disclose permissions required, whether an existing logo is overwritten, reversibility, or error behavior, which are important for a write 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?

The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple two-parameter mutation 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?

Given the absence of annotations and an output schema, the description is too thin for a mutation tool. It does not explain side effects, permissions, or what happens to an existing logo, leaving meaningful behavioral 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%, and both required parameters are documented in the schema. The description adds no additional parameter meaning, 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: 'Set' and 'SharePoint site logo'. It is distinct from all sibling tools, none of which concern logos, so the agent can identify exactly what this tool does without opening the schema.

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 when-to-use, when-not-to-use, prerequisites, or alternatives. It merely states the operation, leaving the agent to infer its place among the many site/page/navigation 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?

With no annotations, the description carries full behavioral burden. It says 'update' but doesn't disclose whether changes are immediate or require publishing, what happens to omitted properties, or any permission requirements. This is a significant gap for a mutation tool with 7 parameters.

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 short sentence, which is concise, but it's under-specified rather than optimally structured. It front-loads the verb and resource, which is good, but the brevity results in missing critical 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?

Given a 7-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is far too sparse. It doesn't explain return behavior, required vs optional parameters beyond the schema's 'required' list, or side effects, leaving the agent poorly equipped to call 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?

Schema description coverage is 0%, so the description must compensate but instead only vaguely mentions 'title' and 'title area' while ignoring the other five parameters (pageId, siteId, titleLayout, showComments, headerImageUrl, showRecommendedPages). This leaves most parameters semantically opaque.

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?

Clear verb ('Update') and resource ('page properties'), and it names example fields (title, title area). Reasonably distinguishable from siblings like create_page, delete_page, and publish_page, though it doesn't explicitly contrast with them.

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?

Offers no guidance on when to use this versus alternatives like update via publish_page or add_section, and no prerequisites or conditions are stated. The agent must infer usage entirely from the name and description.

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 full behavioral burden, but it discloses only that an upload occurs. It omits overwrite behavior, file-size limits, authentication requirements, and return semantics for this mutation 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?

A single sentence with the operation and destination front-loaded. There is no filler or 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?

For a write/upload tool with no annotations, no output schema, and only minimal description, key behavioral context is missing. An agent cannot tell what happens on filename collisions, whether uploads are destructive, or what a successful response contains.

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 75%, so most parameters are already documented in the schema. The description adds file-type examples for the content but does not clarify base64 encoding expectations or folder-path behavior beyond what the schema provides, making the baseline of 3 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 (Upload), resource (file), examples of file types (image, CSS, etc.), and destination (Site Assets). It clearly separates itself from page/webpart siblings, though it does not explicitly name an alternative tool for comparison.

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?

There is no guidance on when to use this tool versus alternatives like add_image_webpart, nor any mention of prerequisites such as required permissions or valid site context. The description only restates the operation.

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