Change Talk configuration

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds important behavioral context: the server flag requirement, the need for user confirmation, and the fact that the tool changes or deletes data. This is consistent with the annotations and goes beyond what structured metadata alone provides.

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?

Four short sentences, each earning its place: purpose, prerequisite, user-confirmation requirement, and a pointer to more detail. It is front-loaded with what the tool does and wastes no words.

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 generic write/delete invocation tool, the description covers the critical constraints: destructive nature, server flag, user confirmation, and where to find body shapes. It does not describe return or error format, but with no output schema and a wide endpoint enum, the essentials for calling it correctly are present.

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 coverage is 67%, so the description is not fully responsible for parameter documentation. The description does help with the body parameter by pointing to talk_list_endpoints for body shapes, but it does not add meaning for the endpoint enum values or path_params beyond what the schema already provides.

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 clearly states a specific action: 'Call a Talk endpoint that changes or deletes data.' This distinguishes it from the read-oriented siblings (talk_status, talk_list_calls, talk_get) and gives the agent a clear sense of when this tool is relevant.

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 gives concrete conditions for use: it requires TALK_ALLOW_WRITES=true and instructs the agent to confirm with the user before calling. It also points to talk_list_endpoints for body shapes. However, it does not explicitly state 'use the read-only siblings for reads,' though this is strongly implied.

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