create-subscription

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

Annotations only provide hints (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description carries the disclosure burden. It adds valuable behavioral context: the notificationUrl must validate with token echo, expiration maximums vary by resource (1 hour for calls, 24h for messages, 3 days for mail), and enabling includeResourceData requires encryptionCertificate + encryptionCertificateId. The creation side-effect aligns with destructiveHint=true, so there is no contradiction. The description enriches rather than repeats 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 first paragraph is verbose boilerplate copied from Microsoft docs, including hyperlinks an agent cannot follow ('see Set up notifications...'). The TIP block is dense but efficient, front-loading required fields before optional ones. There is redundancy — the body requirements are repeated in prose and again structured in the schema. It earns its structural clarity but could trim the doc-link prose.

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 complex operation (nested body object, 4 top-level parameters, no output schema), the description is fairly complete: it covers required body fields, optional rich-notification setup, and the permission precondition. Gaps are minor — it relies on non-clickable external references for details like lifecycleNotificationUrl behavior (Teams) and exact maximum lifetime tables, deferring that to the schema. Overall sufficient for an agent to form a valid 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 75%, borderline high, so the schema already documents most fields well. But the description adds genuine value beyond the schema: permission requirements tied to specific scopes, concrete resource path examples, and concrete expiration maximums that the schema only vaguely references as 'Subscription lifetime.' This helps the agent construct a valid body without external lookups.

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+resource statement: 'Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.' This distinguishes it from the sibling set (update-subscription, delete-subscription, list-subscriptions, get-subscription) — this is the create operation. Nothing tautological; it clearly establishes the tool's function as registering a webhook for change notifications.

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 TIP block gives strong when-to-use guidance: required body fields, concrete resource path examples ('/me/mailFolders/inbox/messages', '/users/{id}/events'), and a permission model ('No dedicated scope — caller must have a read permission for the target resource, e.g. Mail.Read, Calendars.Read'). It explains the validation requirement for notificationUrl. However, it never explicitly contrasts with the sibling subscription tools or states when NOT to use it — usage is implied rather than explicitly differentiated.

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