update_form_share

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

Annotations already provide the core safety profile (idempotent, non-destructive, read-write). The description adds that the returned share is 'refetched via the parent form,' which clarifies the response source, but it does not disclose whether key_value_pairs is merged or fully replaced, nor any side effects beyond updating the share.

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 compact and well-structured with Args and Returns sections, placing the operation first. No filler; each sentence contributes. Slight redundancy with 'Numeric form id' and 'Numeric share id' against schema types is minor and acceptable.

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 description covers the essential call shape and return behavior, and an output schema exists to document the response. Yet for a tool with an open-object key_value_pairs and many sibling share tools, the lack of field enumeration and explicit update semantics leaves an agent uncertain about full usage.

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 carries full parameter burden. It correctly identifies form_id and share_id as numeric IDs and explains key_value_pairs as 'Object with fields to change,' citing 'permissions' as the common case. However, it offers no exhaustive list of supported fields or types beyond permissions, leaving the open-ended key_value_pairs under-specified.

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?

Description uses a clear verb-resource pair: 'Update a share's permissions.' It distinguishes from create_form_share and generic update_share by mentioning the parent form context in Returns, but it doesn't explicitly state that this tool is for form-scoped shares only.

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 or comparison against sibling tools like create_form_share, update_share, or delete_form_share. The only reference to a sibling ('see create_form_share') is for the permissions format, not for tool selection, so an agent receives little direction on choosing this tool.

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