nibwp/wp-search

nibwp/wp-search is a read ability in NIBWP’s wordpress toolset. A safe, side-effect-free call that returns structured, schema-typed data for wordpress — discoverable, permissioned and logged. Like every NIBWP ability it is a typed MCP tool: the agent calls it by name with structured arguments, NIBWP validates those arguments against a schema, checks them against your token’s scopes, runs the operation, and records the call in the audit log. Nothing about it is a black box — you can see exactly what it accepts, what it returns, and what it did.

What wp-search does

nibwp/wp-search is a read ability: it looks up data and returns validated JSON without changing anything on your site. Filter and paginate the results, then chain them into write calls.

When to reach for it

Reach for nibwp/wp-search whenever an agent needs to understand before it acts. Read abilities are how an agent gathers context — finding the right posts, inspecting a record, checking what exists — so that any later write is precise instead of a guess. They are safe to grant freely: a read token can look but never change, which makes this the ideal first ability to give a new agent.

How a call works

Every call to nibwp/wp-search follows the same four-step path, which is what makes it safe to put in an agent’s hands:

• Validate — your arguments are checked against the tool’s JSON schema before anything runs.
• Authorize — the call is checked against your token’s scopes; out-of-scope calls are refused.
• Execute — the operation runs against WordPress through the standard, supported APIs.
• Audit — the call is logged with status, timing, the calling token and the result.

Parameters

The arguments nibwp/wp-search accepts. Anything marked required must be present; optional arguments fall back to sensible defaults.

Walkthrough: a real call

Here is the shape of a typical request — what the agent sends when it decides to use this ability:

tool: "nibwp/wp-search"
args: {
  filters: { status: "publish" },
  per_page: 20
}

And the structured response it gets back, ready to chain into the next step:

200 { items: [ ... ], total: 42 }

What it can do

• Return structured, schema-typed JSON
• Filter, paginate and sort results
• Safe and side-effect-free
• Ready to chain into write calls

Combining it with other abilities

Abilities are most powerful chained. On its own, nibwp/wp-search does one thing well; in a workflow it becomes a step in something larger. A common pattern is to use a read ability such as nibwp/wp-search or nibwp/wp-list-posts to find the right targets, then act on them — the agent decides the sequence, and NIBWP keeps every individual call validated and logged. This is the difference between an agent that can talk about your site and one that can methodically work it.

Safety & control

NIBWP is built so that capable abilities stay controllable. For nibwp/wp-search that means:

Best practices

• Grant it freely — read access is low-risk and the foundation of good context.
• Be specific — the more precise your query, the more useful the result.
• Use it to plan — read first so the agent’s next write is exact, not a guess.
• Combine with search — pair with nibwp/wp-search to narrow large sets.

Specification

FAQ