GravityKit\GravityCalendar\Abilities\Ability

The shape every GravityCalendar ability declares itself in.

A subclass states its own name, wording, category, schemas and annotations, and implements \self::execute() and \self::permission(); \self::config() assembles those into the array Foundation registers. \Bootstrap skips any file under includes/abilities/{Category}/ whose class does not extend this one.

Since: TBD

Source: includes/abilities/Ability.php:26

Details

• Kind: class
• Namespace: GravityKit\GravityCalendar\Abilities

Methods

Method	Description
name()	The ability name, gk-gravitycalendar/{object}-{verb}.
label()	The short human label, shown in Foundation's settings list.
description()	What this ability does, written for the agent that has to choose between it and the one
category()	The category slug, one {@see Bootstrap::categories()} declares. Use the CATEGORY_* constants.
input_schema()	JSON Schema for the input. Build it with {@see self::input_object()}.
output_schema()	JSON Schema for the output. Build it with {@see self::output_object()}.
annotations()	WordPress's annotation vocabulary. Use {@see self::readonly_annotations()},
execute()	Does the work. Returns the output array, or a WP_Error built with {@see Refusal}.
permission()	Whether this caller may run it.
next_steps()	Which abilities usually come next, and when. Declared in {@see Bootstrap::next_steps_map()}.
config()	The config Foundation registers, assembled from everything above.
to_bool()	A boolean input as a boolean.
input_array()	Input as an array, whatever form it arrived in.
mcp_tool_name()	The MCP tool name this ability surfaces as.
tool_name_for()	The tool name for an ability slug, without needing its class.
input_object()	A closed input schema: unknown arguments are refused by WordPress before execute() runs.
output_object()	An output schema in which every listed key is required.
enum_property()	A string property restricted to a list, so the client shows the valid values and
with_example()	A description with an example value appended, in the form every input property uses.
example_call()	One example tool call in prose, for the end of a tool description.
destructive_note()	The sentence every delete ability's description ends with.
calendar_id_property()	The calendar_id input every calendar-scoped ability shares.
form_id_property()	The form_id input.
readonly_annotations()	Annotations for a lookup: GET.
write_annotations()	Annotations for a write that does not delete: POST.
delete_annotations()	Annotations for a delete: DELETE, gated client-side behind the MCP server's destructive switch.
user_can_manage_calendars()	Whether the current user may open a form's calendar settings.
login_refusal()	The one refusal every ability gives a logged-out caller, before it looks anything up.
settings_permission()	Permission for abilities that do what the calendar settings screen does.

Method Reference

name()

abstract public static function name(): string

The ability name, gk-gravitycalendar/{object}-{verb}.

Permanent once published: the MCP tool name is derived from it, so renaming one breaks every client already bound to it.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:95

label()

abstract public static function label(): string

The short human label, shown in Foundation's settings list.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:104

description()

abstract public static function description(): string

What this ability does, written for the agent that has to choose between it and the one

next to it. It is the only documentation an MCP client ever sees.

Say what it does, what to call first, give an example call (\self::example_call()), and for a delete end with \self::destructive_note(). Name other tools the way the model sees them (gc_calendar_get), with \self::tool_name_for(), never by slug.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:118

category()

abstract public static function category(): string

The category slug, one {@see Bootstrap::categories()} declares. Use the CATEGORY_* constants.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:127

input_schema()

abstract public static function input_schema(): array

JSON Schema for the input. Build it with {@see self::input_object()}.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:136

output_schema()

abstract public static function output_schema(): array

JSON Schema for the output. Build it with {@see self::output_object()}.

WordPress validates the return value against this after the work is done and fails the call on a mismatch, so a key that can be null is declared [ 'string', 'null' ].

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:148

annotations()

abstract public static function annotations(): array

WordPress's annotation vocabulary. Use {@see self::readonly_annotations()},

\self::write_annotations() or \self::delete_annotations().

The HTTP method is derived from these: readonly is a GET, destructive plus idempotent a DELETE, anything else a POST.

Returns

• array{readonly:bool, — destructive:bool, idempotent:bool}

Since: TBD

Source: includes/abilities/Ability.php:161

execute()

abstract public static function execute( array $input )

Does the work. Returns the output array, or a WP_Error built with {@see Refusal}.

Parameters

Name	Type	Default	Description
$input	array		Input, already validated against \self::input_schema().

Returns

• array | WP_Error

Since: TBD

Source: includes/abilities/Ability.php:172

permission()

abstract public static function permission( array $input )

Whether this caller may run it.

Reuse the check the matching settings screen or request handler runs (\self::settings_permission()); never a bare capability the plugin does not check.

Parameters

Name	Type	Default	Description
$input	array		Input as received.

Returns

• bool | WP_Error

Since: TBD

Source: includes/abilities/Ability.php:186

next_steps()

public static function next_steps(): array

Which abilities usually come next, and when. Declared in {@see Bootstrap::next_steps_map()}.

Returns

• array<int, — array{ability:string, when:string}>

Since: TBD

Source: includes/abilities/Ability.php:195

config()

public static function config(): array

The config Foundation registers, assembled from everything above.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:206

to_bool()

public static function to_bool( $value ): bool

A boolean input as a boolean.

WordPress's boolean check accepts the strings "true", "false", "1" and "0" and passes them on unconverted, and "false" is truthy in PHP.

Parameters

Name	Type	Default	Description
$value	mixed		The value sent.

Returns

• bool

Since: TBD

Source: includes/abilities/Ability.php:244

input_array()

public static function input_array( $input ): array

Input as an array, whatever form it arrived in.

WordPress's object check accepts an empty string (rest_is_object( '' ) is true) and hands it on unchanged, and a JSON object can arrive as stdClass.

Parameters

Name	Type	Default	Description
$input	mixed		Input as WordPress passes it.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:260

mcp_tool_name()

public static function mcp_tool_name(): string

The MCP tool name this ability surfaces as.

Foundation owns this derivation at runtime (Manager::get_mcp_tool_name()); this reproduces it, so the two have to be changed together.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:282

tool_name_for()

public static function tool_name_for( string $slug ): string

The tool name for an ability slug, without needing its class.

Parameters

Name	Type	Default	Description
$slug	string		The part of the ability name after the slash, e.g. calendar-get.

Returns

• string — e.g. gc_calendar_get.

Since: TBD

Source: includes/abilities/Ability.php:295

input_object()

public static function input_object( array $properties, array $required=[] ): array

A closed input schema: unknown arguments are refused by WordPress before execute() runs.

Parameters

Name	Type	Default	Description
$properties	array
$required	string[]	[]	Names of required properties.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:315

output_object()

public static function output_object( array $properties, ?array $required=null ): array

An output schema in which every listed key is required.

Parameters

Name	Type	Default	Description
$properties	array
$required	string[] | null	null	Required names. Null makes every property required.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:343

enum_property()

public static function enum_property( array $values, string $description, ?string $default_value=null ): array

A string property restricted to a list, so the client shows the valid values and

WordPress refuses anything else.

Parameters

Name	Type	Default	Description
$values	string[]		The allowed values.
$description	string		What it is. The values are appended automatically.
$default_value	string | null	null	Value used when the property is omitted, if any.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:363

with_example()

public static function with_example( string $description, $example ): string

A description with an example value appended, in the form every input property uses.

Parameters

Name	Type	Default	Description
$description	string		What the property is and where to get a valid value.
$example	mixed		A realistic value. Encoded as JSON.

Returns

• string — e.g. "The calendar id. Example: 7."

Since: TBD

Source: includes/abilities/Ability.php:394

example_call()

public static function example_call( array $arguments ): string

One example tool call in prose, for the end of a tool description.

Parameters

Name	Type	Default	Description
$arguments	array		Example arguments.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:414

destructive_note()

public static function destructive_note(): string

The sentence every delete ability's description ends with.

The MCP server refuses destructive tools unless its GRAVITYKIT_MCP_ALLOW_DESTRUCTIVE setting names them, and an agent that meets that refusal otherwise has no idea why.

Returns

• string

Since: TBD

Source: includes/abilities/Ability.php:434

calendar_id_property()

public static function calendar_id_property(): array

The calendar_id input every calendar-scoped ability shares.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:445

form_id_property()

public static function form_id_property( string $description='' ): array

The form_id input.

Parameters

Name	Type	Default	Description
$description	string	''	What the form is for in this ability. Default names gf_list_forms.

Returns

• array

Since: TBD

Source: includes/abilities/Ability.php:471

readonly_annotations()

public static function readonly_annotations(): array

Annotations for a lookup: GET.

Returns

• array{readonly:bool, — destructive:bool, idempotent:bool}

Since: TBD

Source: includes/abilities/Ability.php:496

write_annotations()

public static function write_annotations( bool $idempotent=false ): array

Annotations for a write that does not delete: POST.

Parameters

Name	Type	Default	Description
$idempotent	bool	false	True when sending the same input twice leaves the same state.

Returns

• array{readonly:bool, — destructive:bool, idempotent:bool}

Since: TBD

Source: includes/abilities/Ability.php:513

delete_annotations()

public static function delete_annotations(): array

Annotations for a delete: DELETE, gated client-side behind the MCP server's destructive switch.

Returns

• array{readonly:bool, — destructive:bool, idempotent:bool}

Since: TBD

Source: includes/abilities/Ability.php:528

user_can_manage_calendars()

public static function user_can_manage_calendars(): bool

Whether the current user may open a form's calendar settings.

Both checks the settings screen passes through: Gravity Forms' Forms page, registered with gravityforms_edit_forms (or gform_full_access), and then the calendar tab's own GV_Extension_Calendar_Feed::ACCESS_CAPABILITIES. gravityview_calendar alone opens the tab's check but not the page it is on.

Returns

• bool

Since: TBD

Source: includes/abilities/Ability.php:554

login_refusal()

public static function login_refusal(): ?WP_Error

The one refusal every ability gives a logged-out caller, before it looks anything up.

The run route has no login check of its own, and a refusal that differed by calendar would tell a stranger which calendars exist and how they are set up.

Returns

• WP_Error | null — Null for a logged-in caller.

Since: TBD

Source: includes/abilities/Ability.php:571

settings_permission()

public static function settings_permission( string $action )

Permission for abilities that do what the calendar settings screen does.

Parameters

Name	Type	Default	Description
$action	string		What the ability does, completing "... needs", e.g. "Listing calendars".

Returns

• true | WP_Error

Since: TBD

Source: includes/abilities/Ability.php:588