set_visibility

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses that the flag is persistent, that save_document auto-hides producer-inputs by default, that a subsequent hygienic save may re-hide the object, and how to lock the override in (visibility_hygiene=False). It omits auth/permission requirements and what happens on an invalid handle, but the key survival-of-visibility behavior is disclosed.

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 front-loaded sentences with zero waste. The core action comes first, then the default behavior it overrides, then the caveat and remedy. Every sentence earns its place.

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 simple two-parameter, no-annotation, no-output-schema tool, the description supplies the important behavioral context an agent needs: the persistence semantics and the re-hiding risk with its workaround. The only real gap is parameter documentation, which the schema also fails to provide.

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 define the parameters, and it does not. It never explains that 'handle' identifies the target object, what form a handle takes, or that 'visible' selects the desired state. The surrounding context implies these roles but does not document them, leaving both required parameters semantically bare.

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 and resource: 'Override an object's persistent Visibility flag.' Distinguishes itself functionally by tying its purpose to save_document's auto-hide behavior, so an agent can see it is not a generic property setter. It stops short of naming an alternative tool explicitly, but the role is clear.

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?

Explicitly says when to use it ('Use this to override — e.g. to keep a reference primitive visible next to a derived part') and warns about the interaction with save_document's default visibility_hygiene=True. It does not state hard exclusions or prerequisites, but the context is clear enough to select it over siblings.

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