check_app

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

Adds substantial context beyond the annotations: files are sent over HTTPS to appledger.net, scanned with Trivy and Opengrep, deleted right after, and only git-committable files under 1 MB are sent (with explicit exclusions). It also discloses the side effects — results written to <path>/.appledger — and the two-step consent gate, which the openWorldHint/destructiveHint annotations alone do not convey.

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?

Front-loaded with purpose, then the upload/consent flow, then outputs, then args — a sensible order with no filler. It is long, and the save_link instructions are arguably operational guidance rather than tool description, but nearly every sentence adds information the agent needs.

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?

No output schema exists, yet the description states the return contents (score 0-100, grade, who may use the app, findings with why and remedy), the on-disk artifacts, and the conditional save_link with its 24-hour single-use constraint. Nothing material is missing for a tool with this much side-effect surface.

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 0%, so the description carries the full parameter burden, and it does: path is the absolute folder path, app_name is shown in the report, confirm_upload is only true after user consent to upload to appledger.net, save_to_dashboard=false excludes the check from the dashboard. Each parameter gets meaning beyond its bare name.

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?

Opens with a specific verb+resource ("Scan an app folder with independent security scanners") and states the secondary value (plain-language explanation of findings). It is clearly distinct from siblings like preview_upload or get_fix_prompt, which are narrower steps in the same workflow.

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?

Gives an explicit procedural rule: the first check returns needs_confirmation, show the preview and ask, then call again with confirm_upload=true; later checks don't ask. Also says to offer save_link once, in one line. It never names the sibling tools directly as alternatives, so a 5 isn't warranted.

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