Best practice for scoping a FunctionTool to a single resource id?

[juanzahi]

I'm building a custom FunctionTool for my own ADK agent and want to follow best practice for scoping its permissions to a single resource. Some of the GitHub sample agents in this repo (e.g. the issue triaging one) bind a tool's write access to a single issue/PR number chosen by the workflow, rather than trusting whatever id the model passes in. Is there a built-in ADK primitive for that kind of per-call authorization binding, or is implementing an allowlist set (like AUTHORIZED_ISSUES in the Java samples) the recommended pattern for FunctionTools that take a resource id?

Thanks in advance!

[juanzahi]

@adk-bot could you take a look at this one, please?

[Yoha02]

For a Python FunctionTool, I would enforce this in the tool's application code. Wrapping a callable in FunctionTool does not, by itself, give that callable an authorization policy for your repository or issue. ADK's in-tool guardrail guidance describes using developer-controlled policy data to constrain tool operations.

For one issue selected by a trusted workflow, a simple pattern is to bind the resource when constructing the tool and expose only the comment body to the model:

from google.adk.tools import FunctionTool


def make_comment_tool(
    *, actor_id, repository, issue_number, can_comment, write_comment
):
    def comment_on_assigned_issue(body: str) -> dict:
        """Add a comment to the issue assigned to this run.

        Args:
            body: Text to add to the assigned issue.
        """
        if not can_comment(actor_id, repository, issue_number):
            return {"status": "denied"}
        write_comment(actor_id, repository, issue_number, body)
        return {"status": "ok"}

    return FunctionTool(func=comment_on_assigned_issue)

Here, can_comment and write_comment are your application's policy and backend adapters, not ADK APIs. Construct a separate instance for each authorized scope, using the authenticated actor and validated workflow assignment. Register that returned tool with the agent for that run. The model-facing function has no repository, issue_number, or actor_id parameter to choose or override.

The backend should also enforce authorization at the write itself, using appropriately scoped credentials. Bind the full identity/resource/action tuple: an issue number alone is not unique across repositories. Avoid sharing a mutable global allowlist across users or runs, and do not treat ordinary model-editable session state as authoritative permission data.

If your tool genuinely needs to accept a resource ID, compare it with the trusted run's allowed resource set and reject a mismatch before calling the backend. Injected ToolContext can carry application context without becoming a model argument; the function-tool documentation explains that mechanism. You still need to control who can populate or modify the policy it references.

Validation: this example was prepared with AI assistance and checked locally with google-adk==2.9.2. Seven offline checks passed: body-only schema, allowed call, attempted identity/resource overrides, denied permission, revoked permission, isolation between two scopes, and missing body. The policy and writer were mocks, with no model requests or GitHub writes. In this SDK version, undeclared arguments were filtered before invocation; the attempted overrides therefore could not change the bound target. That is a useful version-specific check, not a substitute for backend authorization.

Relevant implementation: FunctionTool at v2.9.2.