Skip to main content
Glama

list_pending_shares

Read-onlyIdempotent

List shares awaiting your acceptance, covering local and federated shares, so you can decide to accept or decline.

Instructions

List shares other users offered the current user that are waiting to be accepted.

Shares from users on this server wait here when the user turned off accepting shares automatically (a personal sharing setting) or the admin made accepting them necessary; federated shares from other servers wait here unless they come from a trusted server, whose shares are accepted automatically by default. Accept one with accept_share or decline it with decline_share, passing its id and "federated".

Returns: JSON list of pending shares: id, federated, share_type, path (the item's name), item_type, mimetype (both unknown for federated shares until accepted), uid_owner (the sharer; for federated shares a user on the "remote" server), plus for shares from this server displayname_owner, share_with (a group for group shares), expiration, note, label and declined. Nextcloud keeps offering a group share the user declined, so it stays on this list with declined: true; accept_share still accepts it. A declined federated group share also stays here.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.9.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial domain behavior: why shares wait, federated trusted-server behavior, and that declined group shares remain listed and can still be accepted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and well structured, with purpose first and details afterward. The Returns section is somewhat lengthy given that an output schema exists, but the domain nuances it adds justify most of the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool with complex sharing and federation semantics, the description covers the relevant waiting conditions, return fields, and declined-share edge case. It is complete enough for correct invocation.

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

Parameters4/5

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

The tool takes no input parameters, so there are no parameter semantics to document. Per the rubric, zero parameters establish a baseline of 4.

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

Purpose5/5

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

The description states a specific verb and resource: list shares offered to the current user that are waiting to be accepted. It clearly distinguishes the tool from siblings such as accept_share and decline_share, and implicitly from broader share-listing tools.

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

Usage Guidelines5/5

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

It explains when pending shares appear in this list, and explicitly routes the agent to accept_share or decline_share with the share id and federated flag. This provides clear alternatives and usage context.

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

Deploy Server

Other Tools