Skip to main content
Glama
Sign In

Sos Entities

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Sos Search

sos_search
Read-onlyIdempotent

Search US state business-entity registries (Secretary of State) by company name — FL, NY, CO, OR, CT, PA, and TX (Comptroller franchise-tax registrations). Returns each match with entity number, legal name, entity type, status, formation date, principal address, registered agent (an agent's address only when the agent is a business), and the state source, plus data_as_of per state. Name matching is "starts with"; if nothing starts with the name it retries as "contains". Omit state to search all seven at once. Use the entity_number with sos_entity for officers. Sourced from each state's official registry publications.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "Goldman Sachs & Co",
      "limit": 3,
      "state": "NY"
    },
    "name": "sos_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesCompany name or its beginning, e.g. "Publix Super Markets" or "Coors".
limitNoMax results per state (default 10, max 50).
stateNoTwo-letter state. One of FL, NY, CO, OR, CT, TX, PA. Omit to search all.
statusNoFilter by status (default any). NY, OR and PA publish active entities only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/open-world, but the description adds real behavioral detail: name matching is 'starts with' with an automatic 'contains' retry, NY/OR/PA only publish active entities, agent addresses appear only for business agents, and each state carries a data_as_of. These are non-obvious traits an agent could not get from the annotations.

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 the core action and state list, and every clause is informative. The long return-field enumeration is dense but justified because there is no output schema.

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?

With no output schema, the description takes responsibility for describing the return shape (entity number, legal name, type, status, formation date, address, agent, state source, data_as_of). Combined with matching semantics and state coverage caveats, an agent has everything needed to call this confidently.

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 100%, so the baseline is 3, but the description adds value by explaining the matching algorithm behind the required `name` parameter (starts-with then falls back to contains) and by reinforcing per-state limit semantics. The `limit` and `status` explanations largely repeat the schema.

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?

Specific verb + resource: 'Search US state business-entity registries (Secretary of State) by company name', with the exact seven states enumerated and TX's Comptroller franchise-tax scope clarified. It also names the sibling it hands off to (sos_entity) for officers, so an agent can separate it from related entity tools.

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

Usage Guidelines4/5

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

Explicit context is given: omit state to search all seven at once, and use entity_number with sos_entity to get officers. It lacks explicit when-not guidance relative to neighbors like company_register_search or resolve_entity, so an agent must infer which registry tool fits which need.

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

All Sos Entities toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources