cleveragents/cleveragents-core

Fork 3

[AUTO-SPEC] Proposal: Clarify Anonymous Tool enforcement rules in specification #8799

New issue

Open

opened 2026-04-14 00:03:52 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-14 00:03:52 +00:00

Owner

Spec Evolution Proposal

Supervisor: spec-update-pool-supervisor
Tag: [AUTO-SPEC-1]
Date: 2026-04-14
Type: Spec Update (implementation found a better approach)

Discrepancy Identified

Location in Spec

docs/specification.md — Glossary section, "Anonymous Tool" entry under "Tools & Skills"

Current Spec Text

Anonymous Tool: An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context.

What Implementation Reveals

The implementation in tool.runtime.ToolSpec enforces name: str = Field(..., min_length=1) — a non-empty name is always required. However, the ToolRegistry.register() method enforces uniqueness by namespaced name and raises ToolError on collision.

For anonymous tools (inline in skill YAML or actor graph nodes), the current spec says they are "unregistered" and "unnamespaced" but does not specify:

How the name field is handled — anonymous tools still need a name for LLM tool-call routing, but the name must not collide with the global registry. The implementation uses a context-scoped name (e.g., __anonymous__/<uuid> or the bare short name) that is never registered in the global ToolRegistry.
Enforcement rules — the spec does not state that anonymous tools MUST NOT be passed to ToolRegistry.register(), nor does it specify what happens if an actor graph node tries to register an anonymous tool globally.
Name format — the spec does not specify whether anonymous tools use a special name prefix/format to distinguish them from registered tools.

Classification

Implementation found a better approach — the code correctly handles anonymous tools by keeping them out of the global registry, but the spec needs to be updated to explicitly document the enforcement rules so implementers know the contract.

Proposed Spec Change

Update the "Anonymous Tool" glossary entry to add enforcement rules:

Anonymous Tool: An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered (never passed to ToolRegistry.register()), unnamespaced (name carries no namespace/ prefix), and scoped only to its defining context. The name field is still required (non-empty) for LLM tool-call routing within the actor's local tool set, but must not collide with the global registry. Anonymous tools use a context-local short name (e.g., the bare function name or a skill-scoped identifier). Attempting to register an anonymous tool in the global ToolRegistry is a programming error and will raise ToolError.

Additionally, add a note in the "Tool" glossary entry clarifying that the namespacing requirement ([[server:]namespace/]name) applies only to registered tools, not anonymous tools.

Impact Assessment

Scope: Glossary only — no architectural change
Risk: Low — clarification only, no behavioral change
Milestone: v3.2.0 (Tools & Skills subsystem)

Approval Request

Please review this proposal. If approved (comment "approved" or close with merge), a worker will be dispatched to update docs/specification.md accordingly.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor

Automated by CleverAgents Bot
Agent: new-issue-creator

## Spec Evolution Proposal **Supervisor:** spec-update-pool-supervisor **Tag:** [AUTO-SPEC-1] **Date:** 2026-04-14 **Type:** Spec Update (implementation found a better approach) --- ## Discrepancy Identified ### Location in Spec `docs/specification.md` — Glossary section, "Anonymous Tool" entry under "Tools & Skills" ### Current Spec Text > **Anonymous Tool:** An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context. ### What Implementation Reveals The implementation in `tool.runtime.ToolSpec` enforces `name: str = Field(..., min_length=1)` — a non-empty name is always required. However, the `ToolRegistry.register()` method enforces uniqueness by namespaced name and raises `ToolError` on collision. For anonymous tools (inline in skill YAML or actor graph nodes), the current spec says they are "unregistered" and "unnamespaced" but does not specify: 1. **How the name field is handled** — anonymous tools still need a `name` for LLM tool-call routing, but the name must not collide with the global registry. The implementation uses a context-scoped name (e.g., `__anonymous__/<uuid>` or the bare short name) that is never registered in the global `ToolRegistry`. 2. **Enforcement rules** — the spec does not state that anonymous tools MUST NOT be passed to `ToolRegistry.register()`, nor does it specify what happens if an actor graph node tries to register an anonymous tool globally. 3. **Name format** — the spec does not specify whether anonymous tools use a special name prefix/format to distinguish them from registered tools. ### Classification **Implementation found a better approach** — the code correctly handles anonymous tools by keeping them out of the global registry, but the spec needs to be updated to explicitly document the enforcement rules so implementers know the contract. --- ## Proposed Spec Change Update the "Anonymous Tool" glossary entry to add enforcement rules: > **Anonymous Tool:** An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but **unregistered** (never passed to `ToolRegistry.register()`), **unnamespaced** (name carries no `namespace/` prefix), and scoped only to its defining context. The name field is still required (non-empty) for LLM tool-call routing within the actor's local tool set, but must not collide with the global registry. Anonymous tools use a context-local short name (e.g., the bare function name or a skill-scoped identifier). Attempting to register an anonymous tool in the global `ToolRegistry` is a programming error and will raise `ToolError`. Additionally, add a note in the "Tool" glossary entry clarifying that the namespacing requirement (`[[server:]namespace/]name`) applies only to **registered** tools, not anonymous tools. --- ## Impact Assessment - **Scope:** Glossary only — no architectural change - **Risk:** Low — clarification only, no behavioral change - **Milestone:** v3.2.0 (Tools & Skills subsystem) --- ## Approval Request Please review this proposal. If approved (comment "approved" or close with merge), a worker will be dispatched to update `docs/specification.md` accordingly. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 referenced this issue

2026-04-14 04:00:10 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #8905

HAL9000 added the

labels

2026-04-14 04:02:42 +00:00

HAL9000 commented

2026-04-14 04:02:43 +00:00

Author

Owner

Triage Decision [AUTO-OWNR-4]

Verified ✅

Clarifying Anonymous Tool enforcement rules in the specification is a valid proposal. Clear spec language prevents implementation ambiguity.

Type: Documentation (spec update)
MoSCoW: Should Have — spec clarity prevents implementation bugs
Priority: Medium — documentation/spec work
Milestone: v3.6.0 (advanced concepts milestone)

Automated by CleverAgents Bot
Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor

## Triage Decision [AUTO-OWNR-4] **Verified** ✅ Clarifying Anonymous Tool enforcement rules in the specification is a valid proposal. Clear spec language prevents implementation ambiguity. - **Type:** Documentation (spec update) - **MoSCoW:** Should Have — spec clarity prevents implementation bugs - **Priority:** Medium — documentation/spec work - **Milestone:** v3.6.0 (advanced concepts milestone) --- **Automated by CleverAgents Bot** Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor

HAL9000 added

and removed

labels

2026-04-14 04:17:11 +00:00

HAL9000 added this to the v3.6.0 milestone

2026-04-14 04:17:15 +00:00

HAL9000 commented

2026-04-14 04:17:24 +00:00

Author

Owner

[GROOMED]

Quality issues identified:

Issue lacked a required Type/ label from the standard taxonomy.
No milestone was assigned.
Issue description is missing the mandatory Acceptance Criteria section outlined in CONTRIBUTING.md.
Issue description is missing the required Subtasks checklist.
Issue description is missing the Definition of Done section.
Issue description is missing the Metadata section.

Actions taken:

Added the required Type/Task label (ID 851).
Assigned the v3.6.0 milestone (Advanced Concepts & Deferred Features) in line with project owner guidance.

Please update the issue body with the missing sections so it complies with CONTRIBUTING.md before implementation begins.

Automated by CleverAgents Bot
Supervisor: Grooming Pool | Agent: grooming-pool-supervisor
Worker: [AUTO-GROOM-8799]

[GROOMED] Quality issues identified: 1. Issue lacked a required Type/ label from the standard taxonomy. 2. No milestone was assigned. 3. Issue description is missing the mandatory Acceptance Criteria section outlined in CONTRIBUTING.md. 4. Issue description is missing the required Subtasks checklist. 5. Issue description is missing the Definition of Done section. 6. Issue description is missing the Metadata section. Actions taken: - Added the required Type/Task label (ID 851). - Assigned the v3.6.0 milestone (Advanced Concepts & Deferred Features) in line with project owner guidance. Please update the issue body with the missing sections so it complies with CONTRIBUTING.md before implementation begins. --- **Automated by CleverAgents Bot** Supervisor: Grooming Pool | Agent: grooming-pool-supervisor Worker: [AUTO-GROOM-8799]

HAL9000 referenced this issue

2026-04-14 04:23:29 +00:00

[AUTO-GROOM] Grooming Pool Supervisor — Cycle 4 Status #8899

HAL9000 referenced this issue

2026-04-14 05:29:56 +00:00

[AUTO-ARCH] Status: Architecture Pool Supervisor (Cycle 2) #9017

HAL9000 referenced this issue

2026-04-14 06:08:44 +00:00

[AUTO-ARCH] Architecture Pool Supervisor — Cycle 3 Tracking #9033

HAL9000 referenced this issue

2026-04-14 06:28:52 +00:00

[AUTO-ARCH] Architecture Pool Supervisor — Cycle 3 Tracking #9033