SMSTunnel

Find a saved name

find_contact

Read-onlyIdempotent

Look up a person's saved phone number by name in SMSTunnel before sending an SMS. Returns up to 5 name-and-number matches, sends nothing, and never guesses a number.

Instructions

Find the phone number of a person by name. Use it when the user names a person instead of giving a number, for example "text Ana that I'm late". Read-only: it sends nothing.

It searches only the names the user saved in SMSTunnel, not the phone's contacts. It matches the start of any word of the name, ignoring case and accents, and returns up to 5 matches.
One match: still show the user the name, the number and the words, and wait for their OK before send_sms.
Several matches: list them (name and number) and ask the user which one they mean.
No match: ask the user for the number.
Never guess or complete a number.
Works only when the API key is allowed to look up names (a separate switch in the SMSTunnel dashboard, off by default).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "find_contact"
  }
}

Input Schema

Name	Required	Description	Default
`name`	Yes	The person's name or part of it, for example "Ana" or "Ana Pop": 2 to 60 characters, trimmed.

Output Schema

Name	Required	Description
`more`	Yes	true when more saved names match than are shown: ask the user for a fuller name.
`matches`	Yes
`private`	No	true when the account's names are private (only its SMSTunnel desktop app can read them), so none can be looked up here.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.1Nov 5, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the read-only annotations, it discloses that nothing is sent, that only SMSTunnel-saved names are searched, that matching ignores case and accents and matches word starts, that at most five matches are returned, and that lookups require a separate API key permission that is off by default. These are exactly the behavioral details an agent needs.

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

Conciseness5/5

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

The purpose is front-loaded in the first sentence, and the bullet structure cleanly separates matching behavior, result handling, safety rules, and permissions. It is dense but every sentence contributes actionable guidance.

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 one-parameter lookup tool with an output schema and read-only annotations, the description covers the important operational context: permission requirements, matching rules, result limits, and what the agent should do for each outcome. No critical caller information is missing.

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

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the schema documents the single name parameter. The description still adds useful meaning by explaining partial-name matching, word-start matching, and accent/case insensitivity, though it does not need to repeat basic type and length constraints.

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?

The description states a specific verb and resource: find a person's phone number by name. It also scopes the search to names saved in SMSTunnel rather than the phone's contacts, which clearly distinguishes it from adjacent lookup and messaging tools.

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?

It gives an explicit trigger ('when the user names a person instead of giving a number') with an example, and then defines behavior for one match, several matches, and no match. It also says never to guess a number and to wait for user confirmation before send_sms.

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

Deploy Server