Skip to main content
Glama
l33tdawg

(S)AGE

by l33tdawg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Hybrid

sage_find_agent

Find an agent by human name across local and connected SAGEs and return exact addresses for messaging. Use scope=local or peer_chain to narrow results.

Instructions

Find an agent by human name in one lookup across this SAGE and connected SAGEs by default. Uses a bounded substring lookup across display name, immutable registered name, and provider; ASCII matching is case-insensitive, non-ASCII code points require registered casing, and exact field matches rank first across both local and federated results. Same-named agents are returned with distinct exact addresses; choose the intended recipient before sending. No separate sage_federation lookup is needed. Use scope=local to search only this SAGE, or peer_chain to search one exact connected SAGE. Returns exact values ready for sage_message_send.to. This is not a global directory or an online/reachability check: an absent match is not proof that a previously known exact agent_id is unreachable.

Input Schema

NameRequiredDescriptionDefault
nameYesHuman display-name, registered-name, or provider substring to find (for example, "mynah" finds "MYNAH (SAGE Voice Bridge Agent)"). ASCII matching is case-insensitive and bounded; non-ASCII code points require registered casing; exact field matches rank first.
limitNoMaximum matches to return (default: 10, max: 20).
scopeNoSearch local and connected SAGEs together by default. Use local to skip federation network checks; local cannot be combined with peer_chain or peer_cursor.all
peer_chainNoOptional exact connected SAGE chain ID. When set, skips local matches and searches only that peer; useful when both SAGEs have an agent with the same display name.
peer_cursorNoBounded federated continuation returned by an incomplete previous lookup. Omit for the first page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv11.23.24
    • addedInput schema / properties / scope
      Added value: +{
+  "default": "all",
+  "description": "Search local and connected SAGEs together by default. Use local to skip federation network checks; local cannot be combined with peer_chain or peer_cursor.",
+  "enum": [
+    "all",
+    "local"
+  ],
+  "type": "string"
+}
  2. Changed1 schema field changedv11.17.9
    • addedInput schema / properties / peer_chain
      Added value: +{
+  "description": "Optional exact connected SAGE chain ID. When set, skips local matches and searches only that peer; useful when both SAGEs have an agent with the same display name.",
+  "type": "string"
+}
  3. Changed1 schema field changedv11.17.4
    • addedInput schema / properties / peer_cursor
      Added value: +{
+  "description": "Bounded federated continuation returned by an incomplete previous lookup. Omit for the first page.",
+  "type": "string"
+}
  4. Changed1 schema field changedv11.14.2
    • changedInput schema / properties / name / description
      Previous value: -"Exact agent display name, registered name, or provider name to find. ASCII matching is case-insensitive; non-ASCII names use registered casing."New value: +"Human display-name, registered-name, or provider substring to find (for example, \"mynah\" finds \"MYNAH (SAGE Voice Bridge Agent)\"). ASCII matching is case-insensitive and bounded; non-ASCII code points require registered casing; exact field matches rank first."
  5. Addedv11.13.9
  6. Removedv11.13.8
  7. Addedv11.13.0

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does so well: bounded substring matching, ASCII case-insensitivity vs. non-ASCII registered casing, exact-match ranking, deduplication across local and federated results, and the important caveat that an absent match is not proof of unreachability. It does not discuss pagination semantics for peer_cursor or cost/latency of federation beyond 'skip federation network checks,' which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and scope, then alternatives, then return shape, then a clarifying negative. Dense but nearly every sentence carries distinct information; the matching rules are somewhat restated between the leading paragraph and the name parameter description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, no-output-schema, no-annotation tool, it covers everything an agent needs: what is searched, matching rules, deduplication, scope/federation controls, and the shape and downstream usability of results ('exact values ready for sage_message_send.to').

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 name, limit, scope, peer_chain, and peer_cursor precisely. The description reinforces scope=local/peer_chain usage but adds no syntax or format 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource and scope: 'Find an agent by human name in one lookup across this SAGE and connected SAGEs by default.' The final sentences explicitly distinguish it from sage_federation ('No separate sage_federation lookup is needed') and from a global directory/reachability check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use alternatives concretely: 'Use scope=local to search only this SAGE, or peer_chain to search one exact connected SAGE,' and routes the caller downstream ('choose the intended recipient before sending'). It also gives explicit exclusions – this is not a directory or a reachability check.

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

Deploy Server

Other Tools