Checks

Sokie checks a server's files every time it reads them: in sokie check, sokie init and sokie dev, on every deploy, and on every push to a linked repository. Each finding names the file and a rule, so you can look it up here.

$ sokie check
! tools/getPetById.md  `getPetById`'s description is 4 words. Agents choose tools by their descriptions: say what it returns and when to use it, in at least ten words.  [description-thin]
OK: Petstore, 19 tools, 0 prompts, 0 resources.

Errors, warnings and notes

• Errors (✗) mean the server can't be built. They stop a deploy, and sokie check exits with 1, so it can gate CI.
• Warnings (!) are worth fixing, but never stop a deploy.
• Notes (·) are for your information.

Errors

• missing-config: there's no sokie.json.
• invalid-json: sokie.json or a case in tests/ isn't valid JSON.
• invalid-field: a field in sokie.json, a tool's frontmatter or a case has the wrong name, type or value.
• literal-secret: something in the files looks like a real key. Use a secret instead.
• missing-source: the spec named by source.path isn't there.
• invalid-source: the spec can't be read.
• unresolved-ref: the spec refers to a schema outside its own file.
• missing-base-url: there's no address for the API. Set upstream.baseUrl.
• undeclared-secret: a secret is used but not declared under secrets.
• invalid-name: a file in tools/, prompts/, resources/ or tests/ has a name that can't be a tool's name.
• invalid-frontmatter: a file's frontmatter isn't valid YAML.
• case-collision: two names differ only in case.
• missing-description: a tool's file has no body.
• unknown-operation: a tool's operation isn't in the spec.
• excluded-operation: a tool's operation is marked x-mcp: false in the spec.
• auth-without-oauth: a tool sets auth, which only applies to an API that uses OAuth.
• undeclared-argument: a prompt's template uses an argument it doesn't declare.
• missing-template: a prompt's file has no body.
• duplicate-uri: two resources have the same uri.
• codegen: a tool can't be built from its operation; the message says why.
• unknown-tool: a case names a tool that isn't in tools/.
• invalid-case-input: a case's input doesn't fit its tool's input schema.

Warnings

• not-canonical: sokie.json isn't in Sokie's layout. Run sokie fmt.
• stray-file: a file in a definition directory isn't a .md file, or one in tests/ isn't a .json file.
• unused-secret: a secret is declared but nothing uses it.
• unused-argument: a prompt declares an argument its template never uses.
• duplicate-operation: two tools call the same operation.
• unclassified-risk: a tool has no risk, so its method's floor applies.
• risk-below-floor: a tool's risk is below its method's floor, so the floor applies.

These come from reading the tools the way an agent does. Make tools easy for agents to use explains the fixes.

• description-missing: a tool has no description.
• description-thin: a description is under ten words.
• description-restates-name: a description only repeats the tool's name or title.
• name-generic: a name says nothing about the tool, like get or list_data.
• names-confusable: two tools' names differ only in case, separators or plurals.
• list-unbounded: a tool returns a list with no way to ask for less, and no project:.
• effect-understated: a tool's name says delete or send, but its risk is lower.

Notes

• unexposed-operations: the spec has operations with no tool.
• hint-cannot-lower: a tool's hints say it isn't destructive, which its risk overrules.

When a deploy fails after the checks

Some failures only show once Sokie builds the server. The deploy reports them by name:

• MISSING_SECRETS: a secret the server uses isn't set. Set it with sokie secrets set.
• CALLER_KEYS_NEED_PRIVATE: a server that uses each caller's own key or sign-in was deployed public.
• BUILD_FAILED: the server couldn't be built; the findings say why.