trmnl_start_photo_selection

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the mutating, non-idempotent, external-facing nature is known. The description adds 'Changes remote state or starts work' plus an authorization-scope warning, which is consistent but essentially boilerplate; it says nothing about what state is created, whether the operation is resumable, or what a caller should expect afterwards.

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 short and front-loads the action name, which is good, but the endpoint URL line and the two generic sentences ('Changes remote state or starts work', 'Run only within the user-authorized scope') consume most of the text without adding tool-specific information.

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 non-idempotent mutation with no output schema and a low-coverage schema, the description should cover the revision token, the pairing with trmnl_complete_photo_selection, and what the caller receives or must do next. None of that is present, so an agent cannot confidently invoke it end-to-end from this definition.

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 only 33%, so the description needs to compensate, but it only echoes the plugin_setting_id path segment from the endpoint string. The required body.revision field is never explained (presumably a concurrency/version token), and the optional profile parameter's effect on this operation is unaddressed.

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 ('Start Google Photos selection') and pairs it with the concrete endpoint POST /api/plugin_settings/{plugin_setting_id}/configuration/photo_selection, which lets an agent distinguish it from the sibling trmnl_complete_photo_selection. It does not explain what 'starting selection' actually initiates (an OAuth/picker handoff?), so a little ambiguity remains.

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 explicit when-to-use guidance: no mention that this must precede trmnl_complete_photo_selection, no prerequisites, no exclusions. The only guidance is the generic 'Run only within the user-authorized scope,' which is a safety caveat rather than usage routing.

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