Gp Calculate Field

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds a genuine constraint (only Arcade, no code blocks, no Portal FeatureSet input) and mentions a destructive gate, but does not explain permanence, rollback, or required authorization. With annotations present, this is adequate but not rich.

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?

A single dense sentence that front-loads the core action and follows with constraints. It is efficient for what it attempts, though packing multiple distinct requirements into one clause makes the restrictions slightly harder to scan than separate sentences would.

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 destructive, six-parameter tool with 0% schema coverage and only a defaulted expression_type, the description is under-specified. An output schema exists, so return values need not be explained, but the confirmation-gate semantics and parameter meanings are not covered, which is a notable gap for a destructive operation.

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 must compensate for six parameters and it does not. It references 'target path' (likely in_table/confirm_in_table) and 'record count' (expected_count) only obliquely, and never clarifies expression_type, field_name, or the meaning of confirm_in_table as an exact-match confirmation string. This leaves most parameters undocumented.

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?

The description gives a specific verb+resource: recomputing an existing field via restricted Arcade expressions. It also carves out scope boundaries (no Python/VB/code block/Portal FeatureSet). It does not name a specific sibling alternative, but given the very large sibling list with no close analog for field-calculating, this is clear enough.

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?

It implies context (rewriting an existing field's values) and implies prerequisites (destructive gate, target path, record count confirmation), but it never explicitly says when to use this vs. da_update_field_constant or da_update_features, both of which also mutate field values. No when-not guidance beyond expression-language exclusions.

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