Initiate Microsoft Identity Device Code login for profile (default 'default'). Non-blocking: returns within ~1s with user_code + verification_url. A background task continues to poll Microsoft Identity and writes the token on success — the agent should poll sp_auth_status until status is 'signed_in', or until the user completes / cancels the flow.

Idempotency: if a pending session already exists for this profile, the existing session is returned unchanged unless force=True (which cancels and restarts).

AGENT_INSTRUCTIONS: Present the verification code to the user inside a fenced code block (so it can be copied with one click) and present the verification URL as a plain markdown link on its own line. Do not paraphrase, do not embed the code inside prose, do not wrap the URL in bold. Example:

Code:
```
ABCD-1234
```

Sign-in URL: https://login.microsoftonline.com/...

Rationale: in a chat UI, a code inside a fenced block gets a one-click copy button; a bare URL becomes clickable; bold-wrapped links and inline codes do not.

Return the current sign-in state for profile (default 'default'). Three states the agent can act on directly:

• 'signed_in' — valid token on disk (regardless of how it got there: CLI login, prior tool-flow, or just refreshed silently). signed_in_user_upn populated. The agent can proceed.

• 'pending' — Device Code flow in progress. user_code, verification_url, time_remaining_s populated.

• 'none' — no token, no flow. Agent should call sp_auth_begin.

Recently-terminal sessions (expired / failed / cancelled) surface their error via the error field instead of falling back to 'none' — so the agent can render a specific failure message.

AGENT_INSTRUCTIONS: When status='pending', present the verification code to the user inside a fenced code block (so it can be copied with one click) and present the verification URL as a plain markdown link on its own line. Do not paraphrase, do not embed the code inside prose, do not wrap the URL in bold. Same format as sp_auth_begin.

Discover SharePoint sites the signed-in user has access to. query is a free-text site-name search (e.g. 'finance'); omit / leave empty to list all visible sites. Returns each site's id, name, web_url, description, last_modified. Read-only. Use as the entry point when the agent doesn't yet know which site URL to drill into.

List sites the signed-in user has marked as Followed in SharePoint. Useful 'my SharePoint' entry point for an agent starting from the user's curated list rather than guessing site URLs. Not available in service-principal auth mode (no signed-in user) — falls back to a clear error there. Read-only.

List all document libraries (drives) on a SharePoint site — default Shared Documents plus Site Assets, Style Library, and any custom libraries. site_url is the site's web URL. Returns each drive's id, name, web_url, description, drive_type, and quota. Most sp_drive_* tools accept URLs into any library transparently — sp_site_drive_list is the discovery step when the agent doesn't know which libraries exist yet.

List all modern SharePoint Pages (Site Pages) on a site. Returns each page's id, name (filename), title, web_url, description, page_layout, thumbnail_web_url, last_modified, last_modified_by. Read-only.

Fetch a single SharePoint Page including its canvasLayout (sections, columns, web parts) as JSON. page_url shape: https:///sites//SitePages/.aspx. Read-only.

List items in the SharePoint site's recycle bin. Returns each item's id, name, size, deleted_date_time, deleted_from_location (original folder), and deleted_by (display name). Read-only. NOTE: Microsoft Graph does not expose a restore action at site scope; items currently have to be restored via the SharePoint web UI. This tool uses Graph's /beta endpoint — the site-level recycle-bin API has not yet been promoted to v1.0. Schema may shift; we'll migrate when v1.0 lands.

List the immediate children of a SharePoint or OneDrive folder. url is the folder's human-readable web URL (e.g. from a previous sp_search_query hit's web_url, or the SharePoint web UI). Returns each child with name, type ('folder' or 'file'), size, last-modified date, and webUrl. Read-only — does not modify SharePoint state.

Download a SharePoint file's content to a local temp file. Returns the absolute path of the temp file with the original extension preserved. Read-only — does NOT acquire a checkout/lock; use sp_drive_file_checkout for that. url is the file's human-readable web URL (e.g. from sp_search_query hits). The LLM consumes the file via filesystem tools (Read, Bash) — no base64 round-trip.

List a SharePoint file's version history. Returns up to limit versions newest-first, each with id (use with sp_drive_file_version_get), last_modified, last_modified_by (display name or email), and size. Read-only. NOTE: per-version comments aren't currently exposed via Microsoft Graph v1.0 — they land in SharePoint's web UI version history but not in this response shape.

Download a specific historical version of a SharePoint file to a local temp file. Returns the absolute path. Use sp_drive_file_history first to find the version_id you want. Read-only — does NOT acquire a checkout, does NOT modify SharePoint state.

Return items in a SharePoint site's default drive that changed since the optional since cursor — Microsoft Graph delta query. First call (since=None) returns the full item set + an initial cursor. Subsequent calls with the cursor return only created/modified/deleted items since that cursor. Result: {items: [...], cursor: str}. The cursor is opaque — store it (the agent typically puts it in conversation memory or a scratchpad) and pass it back as since. A stale cursor surfaces as a 410 Gone error; drop it and call again with since=None for a full re-sync. Read-only.

List the files this MCP profile currently has checked out (acquired via sp_drive_file_checkout). Returns each entry's original path, when checkout happened, and the local working-copy path. Read-only. With verify=True, additionally queries SharePoint to confirm the server-side lock state (server_locked + lock_holder fields); costs one Graph call per registry entry. Default verify=False is sub-second, registry-only — sp_drive_file_checkin's ETag round-trip catches divergence at write time.

List all SharePoint Lists on a site (Issue Trackers, Tasks, Custom Lists, etc.). Returns each list's id, name, display_name, web_url, description, created_date_time, last_modified_date_time, and template (e.g. 'genericList', 'documentLibrary', 'tasks'). Read-only.

Return the column definitions (schema) of a SharePoint List. Each column: id, display_name, name (internal), description, required, hidden, read_only, indexed, type (text/choice/number/boolean/datetime/person/lookup/calculated/hyperlink/currency). list_url shape: https:///sites//Lists/. Read-only.

List items in a SharePoint List with their full fields expanded. filter is an optional OData $filter expression (e.g. "fields/Status eq 'Open'"). top caps results (default 100, max 5000 per Graph). list_url shape: https:///sites//Lists/. Read-only.

Fetch a single SharePoint List item by id with all expanded fields. Returns id, created_date_time, last_modified_date_time, created_by, last_modified_by, web_url, fields (dict). list_url shape: https:///sites//Lists/. Read-only.

List existing sharing links on a SharePoint file or folder. Each entry: id (use with sp_share_link_revoke), web_url (the share URL), type (view/edit/embed/blocksDownload), scope (organization/anonymous/users), roles, expiration, has_password. Read-only — does not create or revoke. Use sp_share_link_create to make a new link, sp_share_link_revoke to remove one. SCOPE: only sharing-link permissions. For ALL access grants (direct user/group assignments, inherited site permissions, plus sharing links) use sp_share_permission_list instead.

List who has access to a SharePoint file, folder, or site. Pass a site URL for site-level permissions or any item URL (file or folder) for that item's permissions. Returns each permission entry with id, roles (read/write/owner), grantee ({type, display_name, email, link_type, link_scope}), and inherited flag. Read-only — does not modify any permission state. Use this to answer 'who can see/edit this?' before suggesting changes or sharing links. SCOPE: all permission grants — direct user/group assignments, inherited site permissions, AND sharing links. To list only sharing links (and get their id for sp_share_link_revoke), use sp_share_link_list instead.

Search SharePoint document libraries the signed-in user has access to. Returns matching files with name, path, webUrl, last-modified date, and author. Read-only. Filter args: site (URL), folder (path), file_type (extension like 'docx'), modified_after (ISO date). SCOPE: currently driveItem-only (files in document libraries). Searching List items or sites by content is not yet supported — use sp_list_item_list with an OData filter for List-item lookup, sp_site_list for site discovery.