Choose files for an agent handoff using filename decisions. No file contents or credentials.
Scored across 3 tools
diagnose_a2a_request is clearly distinct, but prepare_repository_handoff and repository_safety_preflight both concern repository path metadata and handoff safety. The preflight description is terse and does not clearly explain when to use it instead of the handoff preparation tool.
All names use snake_case and are readable. Two follow a verb_noun pattern, while repository_safety_preflight is a noun phrase, which is a minor deviation.
Three tools is a reasonable size for a focused planning/preflight server. However, diagnose_a2a_request feels somewhat extraneous to the repository handoff planner scope.
The core handoff preparation tool is present, and safety preflight supports it, but the surface lacks a clear way to inspect candidate entries or assemble/validate the final handoff plan. The A2A diagnosis tool is adjacent rather than filling an obvious handoff lifecycle gap.
Diagnose common A2A JSON-RPC SendMessage version and message-shape mistakes. Use when debugging an A2A integration. Send a sanitized request example and selected protocol version, never secrets or headers. Returns fixed field corrections and an authored template. Does not contact an endpoint or certify full conformance.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | Sanitized A2A JSON-RPC body to inspect, not a URL, string or HTTP wrapper. Malformed message fields are allowed for diagnosis. Never include secrets, headers or private content. Entire arguments JSON: at most 16384 ASCII-escaped UTF-8 bytes. | |
| protocolVersion | Yes | Target A2A version from the server's Agent Card, NOT the MCP transport date. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: it does not contact an endpoint and does not certify full conformance, which bounds the agent's expectations about what a 'diagnose' call can prove.
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 short sentences, each doing distinct work: purpose, trigger, input constraint, output and limits. Scope and the key safety warning are front-loaded.
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 diagnostic tool with no output schema, the description supplies both the expected return (fixed field corrections plus an authored template) and the boundaries (no endpoint contact, no conformance certification). Nothing needed to call or interpret 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 both parameters including the enum and the byte limit. The description reinforces the sanitization rule and the source of protocolVersion (Agent Card), but adds little syntax detail 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 (Diagnose) plus the exact resource (A2A JSON-RPC SendMessage version and message-shape mistakes), which is far more precise than the tool name alone. The siblings (prepare_repository_handoff, repository_safety_preflight) are unrelated domains, so no differentiation is needed, but the scope statement is self-sufficient.
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 when debugging an A2A integration" gives clear context, and "never secrets or headers" states a hard precondition. It does not name alternative tools or explicitly say when NOT to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When preparing a user-authorized repository file handoff to another agent or reviewer, call with arguments such as {"entries":[{"path":"src/app.py","kind":"file"}]}. Send permitted relative filenames and kinds only; never file contents, secrets or URLs. Returns exact zero-based include/exclude/skip indexes and reasons for the original entries. This is filename-only planning, not a content security scan or permission to upload.
| Name | Required | Description | Default |
|---|---|---|---|
| entries | Yes | Required: actual user-authorized paths collected from the local repository before calling. The remote server cannot enumerate local files. Do not copy example filenames or send an empty object. |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| skipIndexes | Yes | |
| entryDecisions | Yes | |
| excludeIndexes | Yes | |
| includeIndexes | Yes | |
| manifestDigest | Yes | |
| entriesReceived | Yes | |
| contentSecurityVerified | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent and non-destructive, so the safety bar is partly met; the description adds genuinely new behavior: only permitted relative filenames and kinds may be sent, contents/secrets/URLs are forbidden, and the result includes exact zero-based include/exclude/skip indexes with reasons. It does not discuss scale limits, but the server-side constraint ('remote server cannot enumerate local files') is covered in the 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?
Four tight sentences: trigger first, example second, input constraints third, output and boundary last. Nothing is redundant, though the embedded JSON example makes the first sentence heavy and slightly interrupts front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still summarizes the return contract (zero-based include/exclude/skip indexes plus reasons), and it covers the caller's obligations (supply real authorized paths, never contents or secrets). For a single-parameter, read-only planning tool this is complete enough to call correctly on the first try.
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 a worked example of the entries array and reiterates the filename-only restriction that shapes what values are legal. That is incremental value beyond the schema's own field documentation.
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 ('preparing a user-authorized repository file handoff') and illustrates the input shape with a concrete example, so the agent knows exactly what operation is performed. It also draws a boundary against sibling concerns ('not a content security scan or permission to upload'), though it does not name the sibling tools 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?
It states the trigger condition explicitly ('When preparing a user-authorized repository file handoff to another agent or reviewer') and adds clear exclusions ('filename-only planning, not a content security scan'). It stops short of naming the alternative tools (repository_safety_preflight, diagnose_a2a_request) so routing between siblings still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Zero-effect repository path-metadata preflight. Never send contents, archives, URLs, callbacks, or secrets.
| Name | Required | Description | Default |
|---|---|---|---|
| entries | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully declares zero side effects and explicitly lists data categories never transmitted (contents, archives, URLs, callbacks, secrets), but it does not explain what the tool reads, how it behaves on invalid input, or what it returns.
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?
Two short sentences with no filler, front-loading the core identity before the safety constraints. It is efficient, though arguably under-specified rather than optimally concise.
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 tool with a nested parameter schema, no output schema, and no annotations, the description is too sparse. It omits invocation semantics, return behavior, and sibling differentiation, leaving the agent with insufficient context to call it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. 'Path-metadata' loosely hints at the entries array, but it does not explain the required path+kind object structure, the allowed kind enum values, or the 1024-item limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a resource ('repository path-metadata') and a mode ('preflight'), but the verb is implicit and the overall function remains vague. It partially restates the tool name rather than clearly stating what operation is performed or what a preflight returns.
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?
There is no guidance on when to use this tool versus the sibling prepare_repository_handoff, nor are prerequisites or exclusions stated. The negative constraints ('Never send...') are safety rules, not usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
prepare_repository_handoff1 field changedInput schema / properties / entries / descriptionAdded value: +"Required: actual user-authorized paths collected from the local repository before calling. The remote server cannot enumerate local files. Do not copy example filenames or send an empty object."diagnose_a2a_request3 fields changedInput schema / examplesAdded value: +[
+ {
+ "protocolVersion": "0.3",
+ "request": {
+ "id": 1,
+ "jsonrpc": "2.0",
+ "method": "message/send",
+ "params": {
+ "message": {
+ "messageId": "example-1",
+ "parts": [
+ {
+ "data": {
+ "entries": [
+ {
+ "kind": "file",
+ "path": "src/app.py"
+ }
+ ]
+ },
+ "kind": "data"
+ }
+ ],
+ "role": "user"
+ }
+ }
+ }
+ },
+ {
+ "protocolVersion": "1.0",
+ "request": {
+ "id": 1,
+ "jsonrpc": "2.0",
+ "method": "SendMessage",
+ "params": {
+ "message": {
+ "messageId": "example-1",
+ "parts": [
+ {
+ "data": {
+ "entries": [
+ {
+ "kind": "file",
+ "path": "src/app.py"
+ }
+ ]
+ }
+ }
+ ],
+ "role": "ROLE_USER"
+ }
+ }
+ }
+ }
+]Input schema / properties / protocolVersion / descriptionAdded value: +"Target A2A version from the server's Agent Card, NOT the MCP transport date."Input schema / properties / request / descriptionAdded value: +"Sanitized A2A JSON-RPC body to inspect, not a URL, string or HTTP wrapper. Malformed message fields are allowed for diagnosis. Never include secrets, headers or private content. Entire arguments JSON: at most 16384 ASCII-escaped UTF-8 bytes."diagnose_a2a_requestprepare_repository_handoffrepository_safety_preflightSend API keys and private files to someone else's agent, end-to-end encrypted.
Agent file transfer. No API key to start; price downloads in USDC on Base.
Host files from coding agents; stage on a branch and attach to GitHub PRs.
Securely search and manage workspace context files for AI agents and teams.
Add one secure layer between your agents and this server.
