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

Adds real behavioral context beyond the annotations: workspace has no effect on results, an empty list means nothing is connected, and adb must be on PATH. The read-only claim largely restates readOnlyHint=true, so it is not purely additive, but the environment and scoping disclosures are valuable.

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-loads the core purpose, then the usage guidance, then the return shape and prerequisite. Every sentence carries distinct information with no filler.

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 no output schema, the description supplies the return shape ({ devices: [{ serial, state, extra }] }) and explains the state enum values and extra field, filling exactly the gaps the structured fields leave.

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 100% so the baseline is 3, but the description adds meaningful semantics beyond the schema by stating the workspace parameter does not affect the result, which the schema description alone does not clearly convey.

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 (List) and resource (Android devices and emulators visible to adb), and clearly distinguishes itself from the mutating/querying siblings like adb_shell and adb_install. An agent can tell exactly what this returns without opening the schema.

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?

Explicitly says to 'Call this first to confirm a device is connected' and that its output feeds the deviceSerial parameter of other adb_* and frida_* tools. It even preempts a likely misuse by noting the workspace parameter has no effect.

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

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

Annotations cover the safety profile (readOnly=false, destructive=true, openWorld=true), and the description adds substantial context beyond them: signature precondition, the replace-vs-fail distinction controlled by reinstall, preservation of app data, the success/INSTALL_FAILED_* error surface, and environment prerequisites. The only minor tension is the idempotentHint=true annotation versus the documented failure on a repeat install without reinstall, but the description explains that nuance rather than contradicting it.

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?

Four dense sentences, zero filler: purpose first, then precondition, then the branching reinstall behavior, then return shape and the sibling hand-off. Every sentence carries information an 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?

Although there is no output schema, the description supplies the return shape ({ apkPath, stdoutTail, stderrTail? }) and how to interpret it ('Success' vs INSTALL_FAILED_*), plus environment prerequisites. Nothing needed for correct invocation is missing.

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 100%, so all four parameters are already documented in the schema (apkPath absolute/exists, reinstall -r and data retention, workspace job recording, deviceSerial from adb_devices). The description largely restates the reinstall semantics rather than adding new syntax or format guidance. Baseline 3 applies.

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 precise verb+resource+mechanism ('Install an APK from this machine onto a connected device via `adb install`') and implicitly distinguishes itself from build_apk (output is unsigned, will be rejected) and adb_shell (used for removal/other commands). An agent can place this tool among its 19 siblings without opening a schema.

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?

Explicit about when the tool works and when it fails (APK must already be signed; unsigned build_apk output is rejected), what reinstall changes (fails if present vs. replaces and keeps app data), prerequisites ('adb on PATH and an authorized device'), and names the alternative for other device operations (adb_shell).

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

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

Goes well beyond the annotations (readOnlyHint, openWorldHint) by disclosing that the call does not clear the buffer, that the result is a point-in-time snapshot rather than a stream, and that it requires adb on PATH and an authorized device. These are real operational prerequisites an agent cannot infer from structured fields.

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-loads the core action, then attaches the snapshot/non-destructive caveats, the return shape, a usage tip, and prerequisites in a tight sequence. Every sentence carries distinct information with no padding.

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 no output schema, the description fully specifies the return object (lineCount, truncatedFrom, lines) and its semantics. Combined with prerequisites and non-destructive behavior, an agent has everything needed to invoke this correctly.

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 already 100%, so the schema carries parameter documentation. The description still adds value by explaining the interaction between filter and lines ('cut noise before raising lines') and by describing the shape of the returned line array, exceeding the baseline for a fully-covered schema.

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 ('Dump the device's current logcat buffer and return its most recent lines') and immediately scopes it as a snapshot rather than a live stream. This distinguishes it from the generic adb_shell sibling without the agent needing to open a schema.

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 actionable guidance: 'Use filter to cut noise (e.g. one app's tag) before raising lines,' which tells the agent how to sequence the two parameters. It also clarifies snapshot semantics. However, it never explicitly contrasts this tool with adb_shell or names an alternative, so it stops short of full when/when-not routing.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: it can 'change or delete anything the device's shell user can', it is non-interactive and will hang on input, it requires adb on PATH and an authorized device, and it documents the return shape with specific truncation limits (4000/2000 chars). This is richer behavioral disclosure than the structured fields provide.

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-loads the core purpose, then danger warning, then behavior, then sibling routing, then prerequisites. Every sentence carries distinct value with no filler.

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 no output schema, the description fully compensates by documenting the return object and truncation behavior. Combined with prerequisites, interactivity constraints, and sibling routing, an agent has everything needed to call it correctly and safely.

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 100%, so the schema already documents all three parameters thoroughly with examples. The description adds the return structure but no additional syntax or format meaning for the parameters themselves, so the baseline 3 applies.

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 (run) and resource (one shell command on a connected Android device via adb shell), and explicitly distinguishes itself from siblings adb_install and adb_logcat. An agent can route to the correct tool without opening any schema.

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?

Explicitly names alternatives and the conditions that select them ('For installing an APK use adb_install; for reading logs use adb_logcat'), warns 'only use against a device you control', and notes the non-interactive failure mode (a command waiting for input will hang). Nothing is left to inference.

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

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

Goes well beyond annotations by disclosing the write location (workspace apktool/build), overwrite behavior, unsigned nature, failure condition, and the exact return shape including stderrTail. Annotations already cover idempotency and non-destructiveness, but the description adds crucial operational context.

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?

Every sentence is front-loaded and earns its place: purpose, warning about unsigned output, write location, return value, failure precondition, and requirement. No redundancy or wasted words.

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 mutation tool with no output schema, the description supplies the return object shape and all critical behavioral traits (overwrite, unsigned, failure mode). Combined with the rich annotations and 100% schema coverage, an agent has everything needed to call it correctly.

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 100%, so the schema already documents all three parameters thoroughly. The description reinforces that inputDir must contain apktool.yml and come from decode_apk, but adds no new syntax or format details beyond what the schema provides.

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 (rebuild) and resource (APK) plus the exact input source: an apktool-decoded project directory, possibly edited. This clearly distinguishes it from decode_apk and other siblings without ambiguity.

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?

Explicitly ties usage to decode_apk output ('from an apktool-decoded ... project directory'), warns the result is unsigned and won't install without separate signing, and states the failure precondition (missing apktool.yml) and environment requirement (apktool on PATH). No alternative build tool exists among siblings, so no comparison is needed.

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

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

Annotations declare the safety profile (not read-only, open-world, non-idempotent) but the description adds substantial context beyond that: up to 20 prior turns trimmed to ~12,000 chars, side effects of persisting both message and reply as knowledge-base chat entries, the assistant's limited visibility (only chat history, not reports/notes/files), the remote-or-local provider routing, and the error condition when no provider is configured.

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 the core action and return type, then progressively layers constraints, provider behavior, and sibling routing. Every sentence carries distinct information with no redundancy for a tool of this complexity.

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, open-world conversational tool with no output schema, the description covers the return format (plain text), the history/context limits, the persistence side effects, the provider dependency and its failure mode, and the key gotcha that the assistant cannot see the rest of the workspace. Nothing an agent needs to call it correctly is missing.

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 100%, so both parameters (message, workspace) are already documented in the schema. The description reinforces behavior (history is sent along, entries are saved) but adds little parameter-specific syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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 opens with a specific verb+resource+return type: 'Send a message in a workspace's ongoing chat and get the assistant's reply as plain text.' It explicitly frames the tool as multi-turn conversation, which cleanly separates it from the one-off summarize_text and the read-only list_knowledge siblings.

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?

It gives explicit routing: 'For a one-off summary of some text use summarize_text; to read stored entries use list_knowledge.' This names both alternatives and the conditions that select them, so an agent knows exactly when not to use this tool.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial behavior beyond them: the Gateway validates evidence, rejects non-existent artifacts/entities, defaults status to unverified and source to 'ai', and creates the workspace if missing. That is exactly the operational context an agent needs before calling.

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?

Dense but front-loaded: the core action and evidence-checking rule come first, then defaults, return, and follow-up tool. Every sentence carries information, though the run-on structure could be trimmed slightly.

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 that the created finding is returned and how to modify it. Combined with the validation and defaulting rules, an agent has everything required to invoke a 6-parameter mutation tool correctly.

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 100%, so the schema already documents each field; the description reinforces the evidence semantics with a concrete location example and the artifact/entity existence constraint. It adds meaning beyond the schema rather than merely repeating it, though the gain is modest given full coverage.

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: recording a claim plus its supporting evidence as a finding. It is clearly distinguished from siblings list_findings (reading) and update_finding (changing later), so an agent can route correctly without opening any schema.

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?

Explicitly routes the agent to list_artifacts for citation and to update_finding for later changes, and states the condition that a confirmed finding needs evidence. This is when-to-use and when-not-to-use guidance, not just a restatement of purpose.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, yet the description adds concrete detail they cannot convey: it always writes to a single apktool/decode directory, overwrites prior edits, advises copying elsewhere to preserve work, and requires apktool on PATH. This is exactly the added context that goes beyond structured hints.

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 purpose and its differentiation are front-loaded, and each following sentence carries a distinct load (destructive warning, return shape, dependency). The first sentence is long and load-bearing, but no sentence is wasted.

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 no output schema, the description supplies the return shape (outputDir, fileCount, files with a 200-path cap, stdoutTail/stderrTail). Combined with annotations and full schema coverage, an agent has everything needed to invoke it correctly.

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 100%, so apkPath, noRes, noSrc and workspace are all documented in the schema itself. The description does not add further parameter-level meaning, so the baseline 3 applies.

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 gives a specific verb and resource: decode an APK's resources to editable XML and disassemble its code to smali via apktool. It explicitly distinguishes itself from the sibling decompile_apk by contrasting the editable/rebuildable output against decompile_apk's read-only Java.

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?

It names the complementary tool (build_apk) and the workflow condition that selects this tool — editing and rebuilding. It also names the alternative (decompile_apk) and its read-only nature, so an agent can pick between the two paths without inference.

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

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

Goes well beyond the annotations: discloses that output is reference-only and non-rebuildable, where files are written, that re-runs reuse the same directory, the exact return payload shape, the 200-path cap, the 2-minute wait, the timeout-but-still-running behavior in the Gateway, and the jadx-on-PATH prerequisite.

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?

One dense paragraph, front-loaded with purpose and the decode_apk distinction, then constraints. Nearly every clause carries operational value, though the return-shape and timeout details could be tightened slightly.

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, so the description compensates by describing the returned object fields explicitly, plus truncation, timeout, and prerequisite behavior. Nothing an agent needs to invoke it correctly is missing.

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 100%, so the schema already documents apkPath formats and the workspace semantics; the description adds only the note that a path from get_inbox_apks works. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (decompile) plus resource (APK and related archives) and the tooling (jadx), and explicitly distinguishes itself from decode_apk for rebuild workflows. An agent can pick between the two decompile/decode siblings without opening either schema.

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?

Explicitly names the alternative and its selection condition: 'use decode_apk if you need to edit and rebuild'. It also routes follow-up exploration to list_files or search_code when results are truncated. Both when-to-use and when-not are covered.

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

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

"Only reads" merely restates readOnlyHint=true. The value-add is the undisclosed-by-annotations operational context: frida-tools must be on PATH and a version-matched frida-server must run on the device, both of which cause failures an agent should anticipate. It does not cover rate limits or failure modes beyond the prerequisite note.

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 the core action, then usage routing, then return shape, then prerequisites. Three dense sentences with little waste, though the return-shape sentence is long and slightly packs two shapes together.

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 no output schema, the description appropriately documents the return shape ({ pid, name } / { pid, name, identifier }) and the required runtime prerequisites. The only gap is the workspace parameter's side effect of creating a workspace and recording a job, which the description omits but the schema covers.

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 100%, so the baseline is 3, but the description adds real semantics the schema does not: the identifier field is the package name and an installed-but-not-running app has no real PID. That resolves genuine ambiguity about includeApps output. workspace and deviceSerial are left entirely to the schema.

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 ("List running processes on a device via Frida") plus the scope variant (includeApps adds installed apps). It also distinguishes itself from the sibling frida_trace by naming the handoff relationship, so an agent can tell the two apart without opening either schema.

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?

"Use it to find the package name or PID to pass to frida_trace" gives an explicit situation and names the downstream alternative. It stops short of stating when NOT to use it (e.g., when a PID is already known), so it is clear context rather than full when/when-not guidance.

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

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

Annotations flag destruction and open-world reach, but the description adds the substance: the script runs inside the target app and can modify behavior and state, spawn mode launches the app, the session is forcibly killed after timeoutSeconds, and frida-tools plus a matching frida-server are prerequisites. It also pre-empts the most likely misread (timedOut as failure).

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-loads the action and the non-interactive limitation, then the timeout caveat, then returns. Dense and mostly waste-free, though the return-shape sentence and the evidence-saving sentence overlap slightly in purpose.

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, and the description compensates by naming the return fields, explaining that stdout is script output, and disclosing the workspace JSON artifact with outputPath. For a destructive, non-idempotent tool this covers what an agent needs to call and cite it correctly.

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 100%, so mode/target/script/deviceSerial/timeoutSeconds are already fully documented — this is the baseline-3 case. The description reinforces the timeout semantics ('waits timeoutSeconds') but adds no parameter syntax or defaults beyond the schema.

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?

Specific verb chain (spawn/attach, inject, capture) plus resource (Frida script on a process) and an explicit scope boundary: 'not an interactive Frida session'. An agent can distinguish this from frida_list_processes or adb_shell immediately.

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?

Routes the agent to frida_list_processes for target discovery and clarifies that a timeout is the expected end condition, not an error — a genuine usage-level insight. It lacks explicit when-not-to-use guidance against other execution siblings (adb_shell), so it falls short of 5.

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

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

Annotations already declare readOnlyHint=true, so 'Only reads' is largely redundant. However, the description adds genuinely useful behavior beyond annotations: the tool errors if the entity doesn't exist, and it spells out the return shape. It omits permission/auth needs, but discloses the key failure mode.

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 return shape and error behavior. Every sentence carries information (scope, input source, return format, read-only, error case) with no filler, and the return shape earns its place because no output schema exists.

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 no output schema, the description compensates by describing the return shape ({ entity, edges }). Combined with the error behavior, single required parameter, and readOnly annotation, an agent has everything needed to call and interpret this tool correctly.

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 100% and entityId is already documented as 'Entity id, from list_graph_entities.' The description repeats the same sourcing hint without adding format or syntax detail beyond the schema, so the baseline 3 applies.

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 (Get) and resource (knowledge-graph entity) with an explicit scope: the entity plus every edge touching it. It names the sibling tool list_graph_entities as the source of the required id, so an agent can immediately distinguish it from the list operation.

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?

It routes the agent to list_graph_entities for obtaining the required entityId, which is clear usage context. It stops short of an explicit when/when-not statement or naming alternatives by condition, so it is strong but not fully prescriptive.

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

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

Annotations already cover readOnlyHint=true and openWorldHint=false, and the description reinforces 'Only reads' while adding genuine context: newest-first ordering, the meaning of an empty array (nothing dropped OR inbox disabled), and the filename-to-workspace mapping behavior. It does not mention that the call is recorded as a job, but that side effect is disclosed in the parameter schema.

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?

Purpose, ordering, and downstream routing are front-loaded in the first sentence, and each subsequent clause carries distinct information (return shape, empty-array meaning, naming rule). The run-on em-dash structure makes it dense to parse, keeping it short of a 5.

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 no output schema, the description supplies the return contract itself ({ fileName, path, sizeBytes, detectedAt }, path is absolute) and explains the empty-array case. Combined with the schema's coverage of workspace semantics, an agent has everything needed to call and interpret this tool.

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 100%, so baseline is 3, but the description adds real meaning beyond the schema by explaining the workspace naming derivation ('MyApp-v2.apk' becomes workspace 'myapp-v2') and instructing the agent to pass that derived name. That materially changes how the single parameter is chosen.

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 ('List the .apk files ... in the server's inbox folder') plus ordering ('newest first'), and clearly distinguishes it from generic siblings like list_files and list_workspaces by scoping to the APK inbox. An agent can tell exactly what this returns without opening the schema.

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?

Explicitly names the downstream tools that consume the result (decompile_apk, decode_apk, identify_packer, adb_install) and the condition that selects this tool: needing a real apkPath 'without the user typing or pasting a path'. This is direct when-to-use routing to alternatives.

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

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

Goes well beyond the annotations by spelling out the consequence of idempotency ('never makes a duplicate or changes an existing workspace'), the failure-free repeat-call guarantee, and the initial state of a new workspace (status 'created'). Since there is no output schema, disclosing the return shape { id, name, targetLabel, status, createdAt, updatedAt } is genuinely additive.

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-loads the core semantics, then the idempotency guarantee, then the return shape, then the when-to-use rule — all in four dense sentences with no waste. Every sentence 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?

For a two-parameter mutation tool with no output schema, the description supplies the return fields, initial status, idempotency semantics, and usage condition. Nothing an agent needs to call this correctly is missing.

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 100%, so both parameters are already fully documented in the schema. The description adds no syntax, format, or edge-case detail about 'name' or 'targetLabel' beyond what the schema states, which is the expected baseline 3 when the schema does the heavy lifting.

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+resource ('Get a workspace by name, creating it first if it doesn't exist') and immediately differentiates from siblings by noting that most other tools create their workspace implicitly. An agent can tell exactly what this does and when it is the right call without opening the schema.

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?

Explicitly gives both when-to-use and when-not-to-use: 'safe to call every time you start work on something' and 'you only need this to set a targetLabel or to get the id'. That is a clear routing rule against the many sibling tools that manage workspaces implicitly.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's 'Only reads the file' is redundant. It adds real value beyond the annotations: the external dependency (apkid on PATH, pip install), the per-file scan scope, and the graceful { raw } fallback when APKiD output is not valid JSON.

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 the core action and resource, then the positioning and return/dependency details. Dense but each clause carries information; only the 'Only reads the file' clause partially duplicates the annotations.

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 no output schema, the description compensates by describing the return shape (APKiD JSON grouped by category, with { raw } fallback) and the runtime prerequisite (apkid on PATH). For a three-parameter read-only tool this is complete.

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 100%, so the schema already documents apkPath, workspace, and timeoutSeconds fully. The description adds only an implicit note that multiple files may be scanned ('for each scanned file'), which is marginal beyond the schema. Baseline 3 is appropriate.

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 (Fingerprint) and a precise resource (compiler, packer, obfuscator, anti-debug/anti-VM techniques of an APK), names the mechanism (APKiD's YARA rules), and positions it as a first-pass triage step, distinguishing it from siblings like decompile_apk and scan_secrets.

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?

Explicitly frames when to use it: 'a good first look before deciding how to approach an APK.' It gives clear context for use but does not name specific alternatives or when-not-to-use conditions.

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

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

Annotations cover only readOnlyHint and openWorldHint, but the description adds non-obvious behavior: the call is a read except that it may create the workspace, and results come back newest-first. It also enumerates the returned record shape (including the nested source and tools fields) even though no output schema is declared.

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 and examples, then the return shape, then the id/call-site note and side-effect caveat. Dense but every clause carries information; the parenthetical artifact examples and field enumeration are slightly listy yet justified given the absence of an output schema.

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 no output schema, the description supplies the return structure, ordering, filtering semantics, and the read-with-workspace-creation caveat — everything an agent needs to call and interpret this tool. Nothing material is left implicit.

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 100% — both kind (with example values) and workspace (name not id, created if missing, defaults to 'default') are fully documented in the schema. The description adds no format or syntax detail beyond the schema, so baseline 3 applies.

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 ('List the artifacts recorded in a workspace') and immediately scopes it with concrete examples of what an artifact is (decompiled sources, decoded APK project, rebuilt APK, secret-scan and Frida trace results). This clearly distinguishes it from siblings like list_files, list_workspaces, and list_findings.

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 link 'Artifact ids are what create_finding evidence cites' tells the agent when this listing matters as a precursor to create_finding, and the kind filter is framed as optional. However, it never explicitly contrasts itself with list_files or list_workspaces for the agent deciding between listing tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: it needs no workspace, and it discloses that the payload includes each agent's descriptor (backend tools, permissions, payload keys, declared outputs).

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 the purpose in the opening clause, followed by scope and the usage trigger. The first sentence is dense with parentheticals, which slightly slows reading, but every element 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?

For a zero-parameter, no-output-schema discovery tool, the description fully covers what it returns (capabilities, providing agents, operations, agent descriptors) and its usage trigger. Nothing needed to call it correctly is missing.

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?

The tool takes zero parameters and schema coverage is 100%, so there is no parameter semantics for the description to carry. Baseline of 4 applies.

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+resource ("List what this Gateway can do") and then defines what a capability actually is with concrete examples (java.decompile, android.rebuild, instrument.trace). It also names what is returned (agents, operations, descriptors), so an agent can distinguish this discovery tool from the action-oriented siblings.

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 trigger: "Use it to discover what is available, for example when a plugin might provide something the other tools don't." That is clear when-to-use guidance, but it names no specific sibling or exclusion, so it stops short of the routing precision of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's 'Only reads' is reinforcing rather than novel. It does add genuinely useful behavior the annotations don't carry: truncation semantics when the limit is hit and error behavior when dirPath doesn't exist. Solid extra context, but no auth or rate-limit notes.

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?

Dense and front-loaded: the core action and the recursive variant come first, then the return shape, then the alternative. Every sentence carries information, though the inline return-shape listing makes the single paragraph heavier than necessary.

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 fully documents the return object (dirPath, count, entries with path/isDirectory/size, truncated), including relative-path and byte-unit conventions. Combined with the safety annotations, an agent has everything needed to call and interpret it.

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 100%, so limit, dirPath, recursive and workspace are all documented in structured data already. The description restates the meaning of recursive and the directory-existence requirement without adding syntax or format detail beyond the schema, so the baseline 3 holds.

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 (list) and resource (directory's children), and precisely scopes the recursive variant. It explicitly distinguishes itself from search_code (content vs name) and implies a relationship with read_file, so the agent can place it among siblings without opening a schema.

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 concrete when-to-use context ('to see what decompile_apk or decode_apk produced before reading individual files') and names the alternative for a different task ('To find files by content rather than name use search_code'). Both the trigger and the exclusion are explicit.

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

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

Annotations only supply readOnlyHint=true, but the description adds the return shape (array of findings with evidence sub-objects), the ordering, and the crucial caveat that it is read-only "apart from creating the workspace if it doesn't exist," which the schema confirms records a job. That is real behavioral context beyond the annotation, candidly disclosing a side effect the hint glosses over.

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 sentences, each earning its place: purpose plus return shape, then the dedup routing, then the read-only caveat. The purpose and ordering constraint are front-loaded before the usage note.

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?

There is no output schema, so the description properly carries the return contract by spelling out the finding object and its evidence array. Combined with the filter documentation in the schema, the side-effect disclosure, and the create_finding routing, an agent has everything needed to call it correctly.

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 100%, so status, entityId and workspace are already fully documented, including the enum and the default. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies even though the surrounding prose is strong.

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 (List) and resource (findings), and defines the resource inline as "claims about the target with their status, confidence and evidence," plus the ordering (newest first). It also names the sibling create_finding, so an agent can place it relative to list_artifacts/list_knowledge without opening any schema.

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 when-to-use: "Check it before create_finding so you don't record the same claim twice," which routes the agent to the deduplication workflow. It stops short of stating when NOT to use it or how to choose between it and other read siblings like list_knowledge, so it is clear context without full exclusions.

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

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

The annotations declare readOnlyHint=true (no environment modification), but the description states 'Only reads, apart from creating the workspace if it doesn't exist' and the schema adds that the call is recorded as a job in that workspace's history. Those are real write side effects, so the description's own carve-out directly conflicts with the read-only claim. Aside from the conflict, the disclosure of return shape and sort order would otherwise be high-value.

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?

Purpose is front-loaded in the first clause, and the second sentence packs useful routing and return-shape information rather than filler. It is dense (a full field list plus three cross-references) but no sentence is wasted.

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?

There is no output schema, so the description must describe the return value, and it does: an array of { id, type, name, attributes, artifactIds, createdAt, updatedAt } with the class-specific attributes.file note. Combined with sort order, side-effect disclosure, and sibling routing, nothing an agent needs to call this correctly is missing.

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 100% and all three parameters (q, type, workspace) are already documented there, including the type enum values and the workspace creation side effect. The description adds only sorting ('sorted by name') and no extra filtering syntax, so baseline 3 applies.

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?

Specific verb + resource + scope: 'List the typed entities in a workspace's knowledge graph, sorted by name', and it goes on to define what those entities are (packages/classes from a jadx decompile plus Gateway-API additions). It is cleanly distinguishable from the singular sibling get_graph_entity, which the description itself names.

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?

It routes the agent explicitly: 'Use get_graph_entity for one entity's relationships, and an entity id as entityId in a finding's evidence', which links this tool into the findings workflow. What's missing is when-not guidance (e.g. when to prefer search_code or a filtered q/type query instead of a full listing).

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

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

Annotations cover safety (readOnlyHint=true, openWorldHint=false), and the description adds context the annotations don't carry: the side effect of creating the workspace if absent, that the call is recorded as a job in that workspace's history, and that unfiltered results can be very long. The workspace-creation side effect sits in mild tension with readOnlyHint, but because the description discloses it explicitly rather than hiding it, an agent is not misled.

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 followed by return shape, filtering advice, and the sibling pointer - every sentence carries information. Density is high and a couple of clauses (the 'only reads, apart from...' aside) interrupt the flow, but nothing is wasted.

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 no output schema, the description supplies the return shape (array of id/workspaceId/type/title/content/source/createdAt/updatedAt/relatedEntryIds), ordering, default workspace behavior, and filter tradeoffs. An agent has everything needed to call this correctly and interpret the result.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the consequence of omitting type (all four types, chat turns included) and clarifies that workspace is a name, defaults to "default", and may be auto-created. Slight duplication of the schema's own workspace description keeps it from a 5.

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?

Specific verb+resource: 'List a workspace's knowledge base entries, newest first', then enumerates the four entry types it returns and how reports/notes originate. It also names the sibling it is not (chat_with_workspace), so an agent can distinguish it without opening either schema.

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?

Explicitly states when to filter ('filter to "report" or "note" for findings') and why omitting the filter is costly ('chat turns included, which can be long'). It names the alternative tool and the condition that selects it: 'To ask a question about the findings rather than read them, use chat_with_workspace.'

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the return shape (field list), the status enum values, and ISO 8601 timestamps, which exceeds the annotation bar. It loses a point only because "Only reads" partially restates readOnlyHint.

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 sentences, front-loaded with the core action and scope, followed by the return contract and then the usage routing. No filler; each clause carries information an 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?

With no output schema present, the description compensates by describing the returned object fields and enum values. Combined with the zero-parameter contract and annotations, nothing needed to call it correctly is missing.

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?

The tool takes zero parameters, so the baseline is 4. The description explicitly confirms "takes no arguments", removing any ambiguity about unlisted inputs.

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 ("List every workspace on the Gateway") with explicit scope ("every"). It clearly distinguishes itself from get_or_create_workspace, which it names directly.

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 use case ("see what already exists before choosing a workspace name") and routes to the alternative ("use get_or_create_workspace to make a new one"). When-to-use and the sibling selection rule are both spelled out.

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

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

Annotations already declare readOnlyHint=true, but the description goes well beyond them: the 512 KB truncation limit with a truncated:true signal, the exact return shape, and error conditions (missing path, or directory instead of file). This is materially useful behavior disclosure.

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-loads the core purpose, then layers scope, limits, return shape, and error guidance in a tight, ordered sequence. Every sentence carries distinct information with no redundancy.

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 no output schema, the description fully carries return semantics (filePath, size, truncated, encoding, content) and error behavior, plus the truncation caveat. Nothing an agent needs to call this correctly is missing.

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 100%, so encoding, filePath, and workspace are already documented in the schema. The description's mention of 'absolute path' reinforces filePath but adds little beyond what the schema provides, so baseline 3 applies.

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?

Clear verb (Read) plus resource (file's contents) and scope (one file, by absolute path). The examples - a decompiled source file or AndroidManifest.xml from decode_apk's output - anchor it concretely and distinguish it from sibling listing/search tools.

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?

Explicitly states 'Only reads' and directs the agent to list_files before reading a directory, naming the alternative for that case. It gives strong context but does not enumerate when to prefer search_code or other readers over this one.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is largely covered. The description still adds real value beyond them: 'Only reads files; skips files over 2 MB', the 200-match cap, and the fact that results are persisted to a workspace JSON file returned as outputPath. It does not, however, note any auth or workspace-history side effect of the recorded job.

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 caveat, behavior, return shape, alternative, and side effect — a sensible order. The single dense paragraph is longer than strictly necessary, but each sentence carries distinct 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?

With no output schema present, the description compensates by spelling out the return object (dirPath, filesScanned, matchCount, matches fields, truncated) and the meaning/units of each field. Combined with the size cap and alternative tool, an agent has everything needed to call and interpret this tool.

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 100%, so dirPath, workspace, extensions, and maxResults are already documented in-schema, which sets the baseline at 3. The description adds only mild extra context (dirPath typically being decompile output, and the outputPath side-effect), without clarifying formats the schema does not already cover.

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 ('Recursively scan a directory ... for likely hardcoded secrets') and enumerates the concrete pattern classes it looks for. It also distinguishes itself from the sibling search_code by scoping itself to a curated high-precision set.

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?

Names the typical input source (decompile_apk or decode_apk output), sets expectations with 'not exhaustive, and not a replacement for a maintained secret scanner', and explicitly routes custom patterns to the alternative tool: 'For your own patterns use search_code.' That is explicit when/when-not/alternative coverage.

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

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

Annotations only cover read-only and non-open-world; the description goes well beyond by disclosing the 2 MB file-size skip, the 10-second timeout that errors instead of hanging, and the truncation flag on results. These are exactly the operational traits an agent needs to predict failure modes.

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 dense sentences front-load the purpose, then limits, then alternatives in a logical order. The return-shape sentence is packed but earns its place given there is no output schema; minor density rather than waste.

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 no output schema present, the description compensates fully by spelling out the return object, the meaning of file/line/text/name fields, and the truncated flag. Nothing needed to call or interpret the tool is missing.

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 100%, so every parameter is already documented, and the description adds no new parameter-level guidance. Baseline 3 applies because the schema does the heavy lifting; the return-shape details belong to output semantics rather than parameters.

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 ('search a directory tree for a regular expression, line by line'), and immediately differentiates from the sibling scan_secrets by routing credential searches there. An agent can place this tool precisely without opening the schema.

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 concrete use cases ('a permission string or URL in decompiled output') and an explicit alternative with its selecting condition ('To look specifically for hardcoded credentials use scan_secrets instead'). The when-to-use is grounded and the alternative is named.

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

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

Annotations declare readOnlyHint/openWorldHint, but the description adds far more: the text is sent to a possibly-remote third-party provider with an explicit privacy warning, it errors when no provider is configured, output is capped at ~512 tokens, and it persists nothing to the knowledge base. These are exactly the behavioral traits structured fields can't 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?

Purpose and return value are front-loaded, followed by the privacy caveat, error condition, and the routing alternative in tight sentences. Every sentence carries distinct, non-redundant 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?

With annotations covering safety and a 100%-covered schema, the description still supplies the missing pieces an agent needs: output shape, provider/privacy implications, failure mode, and the alternative tool. Nothing material is absent.

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 100%, so content/workspace/instructions are already documented. The description adds only the output shape ({ summary }, ~512 tokens) rather than parameter-level syntax. Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource (summarize text) and a concrete scope ('e.g. long tool output'), plus names the sibling it differs from (chat_with_workspace). An agent can distinguish it from the workspace-chat tool without opening either schema.

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?

Explicitly says when not to use it — 'Doesn't save anything to the knowledge base' — and names the alternative with its selecting condition: 'to ask questions about a workspace's accumulated findings use chat_with_workspace instead.' The 'e.g. long tool output' example gives a concrete use context.

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

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

Goes well beyond the annotations (which only declare non-destructive, idempotent, non-open-world). It discloses the crucial replacement semantics of evidence (replaces, not appends), that evidence is validated like create_finding, the confirm-requires-evidence rule, the return value, and atomic failure behavior ('the change is rejected, in which case it is left as it was'). This is exactly the mutation/validation context an agent needs and that structured fields alone don't 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?

One dense paragraph that front-loads the purpose and field list, then layers behavioral constraints. Every sentence carries information (replacement, validation, minimum input, return, error). It is slightly long and packs several ideas into one block, but there is little waste.

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 5-param mutation tool with no output schema, the description covers what changes, the replacement/validation rules, the return value, and failure semantics. Nothing an agent needs to call it correctly is missing.

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 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: evidence replaces existing evidence, is validated identically to create_finding, and at least one non-findingId field is required. It doesn't add enforcement detail beyond what the nested evidence schema already provides, but the replacement rule is meaningful new semantics.

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 (Change) and resource (a finding) and enumerates the mutable fields (status, confidence, reasoning, evidence), so the agent knows exactly what the tool mutates. It is clearly distinct from create_finding/list_findings by function, though it never names or contrasts a sibling explicitly, which keeps it short of a 5.

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 concrete usage conditions: confirm only once evidence supports it, mark contradicted otherwise, and supply at least one field besides findingId. It also states the precondition that a finding can't be confirmed without evidence. It stops short of explicit when-not-to-use or an alternative-routing statement, so it is clear context rather than full selection guidance.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the exact return shape, defines each status value, warns that 'verified' does not prove the claim is true, states items without a location or in single-file artifacts are 'unverified', notes the finding's status is never modified, and documents the error case (nonexistent finding).

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-loads the purpose in the first sentence and every subsequent sentence carries real information. The inline enumeration of the return object is dense but does not pad, though it makes the paragraph heavy to scan.

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 fully specifies the response fields and status semantics, plus edge cases and the error condition. An agent has everything needed to call it and interpret results correctly.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents findingId and its source (list_findings or create_finding). The description adds no further syntax or format detail beyond that, which is the expected baseline.

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 ('Check a finding's evidence against the files it cites') and immediately scopes what counts as checkable (items with a parseable location). It is clearly distinct from the sibling mutation tools create_finding and update_finding.

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?

Explicitly routes status changes to 'update_finding for that', and clarifies the tool is read-only validation rather than modification. It does not state the positive trigger (e.g. call after create_finding to sanity-check citations), so usage is implied rather than fully specified.

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