Call an app function

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=true, so the description's additional context about outbound network requests, allowlisted gateways, argument validation, and receipt-per-write adds meaningful behavioral detail. It doesn't contradict annotations. However, it could more explicitly address the destructiveHint implications (e.g., what writes occur and their effects).

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 a single dense sentence that front-loads the core action and packs in key behavioral details without waste. It could be slightly more structured for readability, but every clause 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?

With an output schema present, the description needn't explain return values, but it does mention the reply carries the return value plus a receipt per write, which is helpful. For a tool with 5 parameters, nested objects, and complex annotations, the description covers most essential aspects: function execution, network behavior, argument validation, and failure handling. It could be more complete by addressing the actor parameter or edge cases, but it's largely sufficient.

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 20%, so the schema documents only command_id's idempotency purpose. The description adds some meaning by noting that args are checked against declared params and that failures return the declared schema, but it doesn't explain the roles of app, function, or actor parameters beyond what their names imply. With low coverage, more parameter detail would be expected.

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 what the tool does: run an app-declared function with data in/data out. It distinguishes itself from siblings like open_app or get_app_html by emphasizing 'no UI needed.' However, it doesn't explicitly name or contrast with any specific sibling tool, leaving some ambiguity about when to choose this over data operations or file operations.

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 implies usage for running declared functions without UI, but doesn't explicitly state when to use this vs alternatives like data_add_item or open_app. No exclusions or prerequisites are mentioned, leaving the agent to infer context from the purpose statement alone.

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