create_share_link

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds meaningful context beyond that by disclosing the write-flag prerequisite and warning twice that the endpoint is not live-validated. It still omits what the share link contains, whether it expires, or who can use it, which would be the highest-value behavioral detail for a share operation.

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 endpoint and mutation flag, but 'Not live-validated' and 'Mutation behavior has not been live-tested' say the same thing twice, wasting one of only five sentences. The external doc reference is also not actionable on its own.

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?

An output schema exists so return values needn't be explained, but for a four-parameter write endpoint with zero schema coverage the description leaves payload shape, query usage, and the confirm_destructive flag entirely undefined. An agent could not construct a correct call from this definition alone.

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% for four parameters, so the description must compensate and largely does not. Saying payload is 'documented in docs/api.md' pushes semantics to an external document, and query and confirm_destructive are never mentioned; 'No path parameters' is the only real parameter guidance, though it usefully signals that the schema's path field should be left null.

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 names the endpoint (POST /v1/share) and the tool name implies creating a share link, so the resource is identifiable. However it never plainly states what a share link is or what it grants, and gives no differentiation from siblings like create_friend_invite or subscribe_shared_flights.

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 only usage-relevant information is the prerequisite that FLIGHTY_ALLOW_WRITES=true is required. There is no guidance on when to use this tool versus alternatives, no mention of when-not to use it, and no reference to any sibling tool.

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