Concepts

Building blocks and server-side compilation

On prompty.tools a prompt is assembled from a task plus reusable building blocks: a persona (who the prompt speaks as), tones (style), an output (format), and constraints (rules). When you create or update a prompt you pass the task text and the IDs of the building blocks - the platform resolves them and compiles the final prompt text server-side. The compiled text is returned as compiledPrompt by get_prompt.

The canonical creation flow:

search_tones / create_persona / ...   -> collect building-block IDs
create_prompt(task, IDs, isPublic)    -> platform compiles, returns the new id
get_prompt(id)                        -> read the compiled prompt text

Persona references use the version id. Personas are versioned, and prompts pin a specific persona version. Pass personaVersionId, taking the value from latestVersionId (get_persona), versionId (search_personas items), or versionId (create_persona response).

Scopes

Every search tool accepts a scope:

Scope	Returns
`public` (default)	Community items visible to everyone.
`mine`	Only the API key owner's items, public and private.
`favorites`	Items the key owner has favorited.
`all`	Everything accessible: public plus the owner's private items.

Pagination

List results return items, total, page, pageSize, hasNext, and hasPrev. The platform only accepts these page sizes: 6, 12, 24, 48, 100 for lists (default 12) and 10, 20, 50 for version lists (default 20). Request the next page by repeating the call with page + 1.

Search and tags

search matches title and description (max 200 characters). tag filters by one exact tag. Both can be combined.

Rate limits and quotas

Every tool call is one API request. Daily quotas per subscription tier: free 20, pro 1,000, teams 10,000. Requests are additionally limited to 30 per minute per action. On HTTP 429 the server reports the limit and a Retry-After when available; it never retries automatically.

Errors

Failed calls return an MCP tool error whose text carries the platform error name, HTTP status, message, and - for 5xx responses - a requestId to quote when reporting issues:

PromptyNotFoundError (HTTP 404): Prompt not found
PromptyAuthError (HTTP 401): Unauthorized
PromptyRateLimitError (HTTP 429): Rate limit exceeded. Retry-After: 42s. ...

A 404 also covers building-block references that exist but are not accessible to your key.

Visibility

Every create tool requires an explicit isPublic choice - there are no silent defaults, so an assistant never accidentally publishes private material (the platform's own defaults differ per resource, which is why the server insists). Prompts and personas have dedicated set_*_visibility tools; tones, outputs, constraints, and libraries change visibility via their update tools.

Versioning

Resource	Versioned	Changelog
Prompts	Yes - every update creates a version	Required on update
Personas	Yes - every update creates a version	Optional on update
Tones, outputs, constraints	No - updates overwrite	-
Libraries	No - metadata updates overwrite	-

Updates take the full new state, not a diff: omitting a building-block reference on update_prompt removes it from the new version.

What the server deliberately cannot do

Delete anything. Deletion stays in the dashboard. The closest tool, remove_prompt_from_library, only removes a membership and is reversible.
Mint API keys. Keys are created in the dashboard and passed in via PROMPTY_API_KEY.