Update Program Resource

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

Annotations already declare write/destructive/idempotent/openWorld, so the safety profile is covered. The description adds genuine context beyond them: partial-update behavior ("Only supplied fields change"), the one-time uploadTicket plus unmodified uploadResult requirement for FILE replacement, and campaign targeting via campaignId or the GROWSURF_CAMPAIGN_ID env var.

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?

Three tight sentences, front-loading the update/partial semantics before the conditional FILE caveat and the targeting rule. The API-reference URL is useful rather than filler; no redundancy against structured fields.

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 tool gated by a complex conditional schema (if/then upload pairing, anyOf requiring at least one updatable field), the description covers the key interactions and an output schema exists so return values need not be explained. The one gap is the absence of any usage routing relative to sibling resource tools.

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?

With schema description coverage at only 42%, the description must compensate, and it does for the non-obvious params: position is zero-based, FILE needs uploadTicket + the unmodified uploadResult from the secure upload flow, and campaignId defaults to GROWSURF_CAMPAIGN_ID. Self-evident params (title, description, isPublished) are left to the schema, which is reasonable.

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?

States a specific verb+resource ("Update ... participant resource field, or move it to a zero-based position") and clarifies partial-update semantics with "Only supplied fields change." It is clear what the tool does, though it never names or distinguishes itself from the sibling create/delete/list program-resource tools.

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 description says what can be updated (at least one field, or position) but gives no when-to-use guidance, no exclusions, and no routing to alternatives such as growsurf_create_program_resource or growsurf_delete_program_resource. An agent gets no help deciding between this and its siblings.

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