syncky_send

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

Annotations already declare a non-read-only, non-idempotent, open-world call, and the description adds genuinely new context: the receiving phone enforces policy and consent, and 'sent' means relay delivery only, not processing. That last clause is a valuable caveat an agent could not derive from the annotations. It does not cover failure modes or what happens when approval is denied, so it falls short of a 5.

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 tight sentences, front-loaded with the core action, and no filler. The middle sentence is somewhat compressed — 'writes, diagnostics and access requests' is cryptic without mapping to a parameter — but the overall economy is good.

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 nested-payload, open-world send with no output schema and zero schema description coverage, the description covers the delivery semantics and approval rule well. It is not complete enough to call the tool confidently, since the type discriminator and validate flag remain unexplained and no return shape is described.

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% across 4 parameters including a nested object, so the description carries the full burden. It clarifies that 'to' is a confirmed phone and that the payload is caller-owned JSON ('inner'), but says nothing about 'type' at either level or about 'validate', leaving half the schema 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 states a specific verb ('send') and resource ('caller-owned JSON') with a scoped target ('one confirmed phone'), which separates it from siblings like syncky_inbox and syncky_ack. It stops short of naming an alternative explicitly, so differentiation is inferable rather than stated.

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?

'Obtain owner approval for writes, diagnostics and access requests' gives a real precondition for certain sends, which is more than most definitions offer. However, it never says when to choose this tool over syncky_ack or syncky_inbox, and the categories 'writes, diagnostics and access requests' are not mapped to any parameter, leaving the agent to guess which sends need approval.

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