pocketbase-mcp

by Touexe

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

find_records

Read-only

Query records in a PocketBase collection by ID, filter, or fetch all matching entries.

Instructions

USE WHEN you need to query or look up records in a collection.

EXAMPLES:

By id: find_records(collection="posts", record_id="abc123")
By filter: find_records(collection="posts", filter_template="status = {:s}", filter_params={"s": "published"})
All records: find_records(collection="posts", fetch_all=True)

NEXT STEPS: write_record to mutate, describe_collection for field names.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number (1-based).
`sort`	No	Sort expression, e.g. '-created,title'.
`expand`	No	Comma-separated relation fields to expand.
`fields`	No	Comma-separated fields to return (projection).
`per_page`	No	Records per page.
`fetch_all`	No	Fetch every matching record across all pages. Caution: may be large.
`record_id`	No	Fetch exactly one record by id. Mutually exclusive with filter_template.
`collection`	Yes	Collection name or id.
`filter_params`	No	Values for {:name} placeholders in filter_template.
`filter_template`	No	PocketBase filter with {:name} placeholders, e.g. 'status = {:s}'

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 16, 2026

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, covering the read-only safety profile. The description adds useful invocation modes (by id, by filter, fetch_all) but does not disclose additional behavior such as pagination limits or result size beyond what the schema already notes.

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?

The description is front-loaded with the use condition, followed by compact examples and a next-steps line. It is somewhat long but each section contributes; there is no filler.

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

Completeness4/5

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

Given 10 parameters and an output schema, the description plus schema covers the main query modes and sibling routing. It does not spell out the record_id/filter_template mutual exclusion, but the schema documents that constraint.

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 description coverage is 100%, so the schema already documents all parameters. The examples add extra meaning by showing how collection, record_id, filter_template, filter_params, and fetch_all combine in realistic calls.

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 opens with 'USE WHEN you need to query or look up records in a collection,' naming a specific action and resource. It also distinguishes the tool from siblings by pointing to write_record for mutation and describe_collection for field names.

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?

It gives a clear triggering condition ('USE WHEN you need to query or look up records') and an explicit routing hint: 'write_record to mutate, describe_collection for field names.' It does not enumerate all alternatives like bulk_write, but the guidance is sufficient for most routing decisions.

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

Deploy Server