JSONPad docs, API, SDK and CLI references, and offline checkers for write rules and flows.
Scored across 14 tools
Each tool targets a distinct purpose: doc discovery (list_docs/search_docs/read_doc), targeted accessors (get_api_endpoint/get_sdk_method/get_cli_command/get_plan_limits/lookup_error), and document validators (check_flow/check_write_rules/eval_write_rule/validate_sync_document/validate_token_permissions). The only mild overlap is that read_doc can also read sdk/cli pages that get_sdk_method and get_cli_command serve, but the descriptions clearly delineate targeted lookup versus full-page reading.
Every name follows a clean verb_noun snake_case pattern: check_*, eval_*, get_*, list_*, lookup_*, read_doc, search_docs, validate_*. No mixed conventions or ambiguous verbs.
14 tools sit right in the well-scoped sweet spot, and each earns its place by covering a distinct doc category or validation type. Nothing feels redundant or padded.
The surface comprehensively covers documentation discovery, API/SDK/CLI reference, error codes, plan limits, and local validation of flows, rules, sync documents and token permissions. Minor gaps exist (e.g. no dedicated quickstart/getting-started accessor), but read_doc covers those pages as a workaround.
Compile a flow document (flows-v1) with the same engine the API uses, and run its tests (flow-tests-v1) against in-memory data. Returns diagnostics (with JSON pointers into the document), what the flow reads and writes, and why each failing test failed. Costs nothing and sees no data.
| Name | Required | Description | Default |
|---|---|---|---|
| flow | Yes | The flow document | |
| tests | No | The flow tests: a flow-tests-v1 document, optional | |
| knownLists | No | Path names of lists that exist, so the flow using any other list is warned about |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| diagnostics | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: compilation uses the same engine as the API, tests run against in-memory data, it returns diagnostics with JSON pointers, reads/writes analysis, and failure reasons, and it incurs no cost and sees no data. This is rich but does not cover auth requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, followed by return details and a safety/cost note. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully explained. The description nevertheless summarizes key outputs (diagnostics, reads/writes, failure reasons), covers the execution model, and aligns with annotations. Given the 3-parameter schema with full descriptions, nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning by specifying the document format version (flows-v1) for the flow parameter, which the schema only calls 'The flow document'. It does not clarify the knownLists parameter, but the schema already documents it, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific compound verb (compile and run tests) on a specific resource (flow document, flows-v1) using the same engine as the API. It distinguishes itself from sibling tools like check_write_rules or validate_sync_document by focusing exclusively on flow compilation and test execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: the tool is for checking a flow document and its tests. However, the description provides no explicit when-to-use or when-not-to-use guidance, nor does it name any alternative tool or condition under which another sibling should be preferred. 'Costs nothing and sees no data' hints at safe usage but is not a routing guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compile a list's write rules with the same engine the API uses, and run their tests (a rules-tests-v1 document). Returns every diagnostic with its line and column, and for each failing test what it expected, what happened, and how each rule came out. Costs nothing and sees no data: lookups find the test document's items. Use it before saving rules.
| Name | Required | Description | Default |
|---|---|---|---|
| rules | Yes | The rule text, or its lines as an array (as in a schema sync document) | |
| tests | No | The rule tests: a rules-tests-v1 document ({ "tests": [...] }), optional | |
| knownLists | No | Path names of lists that exist, so lookups into any other list are warned about, as the API does when rules are saved |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| diagnostics | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive/closed-world, so the marginal bar is met by genuinely new traits: no cost (no quota consumed) and no data exposure, plus a concrete sketch of what is returned for failing tests. Missing only whether results are cached or size-limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, followed by return semantics and the when-to-use cue; every sentence carries content. The telegraphic "Costs nothing and sees no data" phrasing is dense but earns its place as behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering the safety profile, the description supplies the remaining needed context: scope, engine fidelity, cost/data stance, and invocation timing. Sufficient for an agent to select and call it correctly without opening the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 rules, tests, and knownLists. The description adds only light corroboration ("lookups find the test document's items"), not new syntax or format detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: compile a list's write rules with the API's own engine and run their tests. The scope (a rules-tests-v1 document, diagnostics with line/column, per-test outcomes) clearly separates it from eval_write_rule and validate_sync_document, though no sibling is named by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use it before saving rules" gives an explicit timing/context for invocation, and "costs nothing and sees no data" clarifies its safe pre-check role. It stops short of naming the alternative tool (e.g. eval_write_rule) for single-rule checks or stating when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check one write against a rule set, as the API would, and say whether it would be allowed, denied (403) or failed (400), which statement decided it, and (with trace) what every expression evaluated to. The write is shaped like a rule test case: action, identity, token, old, new, patch, merge, now. Costs nothing and sees no data.
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | Items for lookups to find: { "<list>": { "<item id or alias>": { "data": ... } } } | |
| rules | Yes | The rule text, or its lines as an array (as in a schema sync document) | |
| trace | No | Include the value of every expression | |
| write | Yes | The write to check | |
| identities | No | Named identities the write can refer to |
| Name | Required | Description |
|---|---|---|
| ok | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered; the description still adds real value by clarifying this is a side-effect-free simulation that "sees no data" and explains the trace flag's effect on the response (every expression's evaluated value). It stops short of describing error handling or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, and the core purpose plus outcomes are front-loaded before the write-shape detail. Every clause contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter nested tool with an output schema, the description covers purpose, outcome semantics and the trace behavior, so an agent has enough to call it correctly. Minor gaps remain around how rules/identities/items interact and how failures are surfaced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 rules, items, identities, trace and the nested write fields; the baseline is 3. The description adds only a prose enumeration of the write shape (action, identity, token, old, new, patch, merge, now), which largely restates what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (check/evaluate) and resource (one write against a rule set) and enumerates the three outcomes it reports (allowed, 403 denied, 400 failed) plus which statement decided it. It is clear what the tool does, though it never explicitly contrasts itself with the close sibling check_write_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"As the API would" and "costs nothing and sees no data" imply this is a safe dry-run/simulation for pre-flighting a write, which hints at when to reach for it. However, there is no explicit statement of when to use it versus check_write_rules or validate_sync_document, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full contract of one REST API endpoint: parameters, headers, request body, responses and examples, and the JavaScript SDK method that calls it. Find it by id (the docs page slug, e.g. "item-restore"), by method and path (templates or concrete paths both work: "/lists/my-list/items/abc"), or by a description.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The endpoint id, from list_api_endpoints | |
| path | No | The path, e.g. /lists/{listId}/items | |
| query | No | What the endpoint does, e.g. "restore a deleted item" | |
| method | No | The HTTP method |
| Name | Required | Description |
|---|---|---|
| endpoint | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the breadth of the returned contract and its multi-mode lookup, but says nothing about behavior on non-matches or ambiguous lookups, which matters for a lookup with three overlapping selectors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what the tool returns before moving to lookup modes. Dense but every clause carries information; only minor cost is the slightly run-on enumeration of contract contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, and annotations cover the safety profile. Given the tool's simplicity (read-only lookup with complete schema coverage), the description is complete enough; only error/ambiguity handling is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, but the description still adds meaning: it clarifies that id is the docs page slug with an example ('item-restore'), that path accepts both templated and concrete forms with an example, and that query is a free-text description. This is genuine value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (the full contract of one REST API endpoint), and enumerates exactly what the contract contains: parameters, headers, body, responses, examples, and SDK method. This distinguishes it from list_api_endpoints by making clear it returns one full endpoint rather than a list, though it does not name that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains three ways to locate an endpoint (by id, method+path, or description), which implies usage but never states when to choose this tool over list_api_endpoints or get_sdk_method, nor any when-not condition. Guidance is present but inferential rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The usage, arguments and options of a jsonpad command line tool (@basementuniverse/jsonpad-cli) command, and whether it works offline. Find it by name ("rules test", "jsonpad sync-schema --dry-run") or by what it does.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The command, e.g. "sync-schema" or "jsonpad rules test" | |
| query | No | What the command does, e.g. "export items to a file" |
| Name | Required | Description |
|---|---|---|
| command | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail — that the result indicates whether the command works offline — but says nothing about error behavior or result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single tight sentence that front-loads the payload (usage, arguments, options) before the lookup modes. Slightly dense with two example blocks, but no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not needed here, and the safety profile is covered by annotations. The description covers both lookup paths and the offline flag, leaving little an agent would need before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description's examples of name and query values reinforce the same information, adding little beyond what the schema provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (a JSONPad CLI command), enumerating what is returned: usage, arguments, options, and offline capability. It also names the concrete package (@basementuniverse/jsonpad-cli), which cleanly separates it from siblings like get_sdk_method and get_api_endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear lookup modes — by name ("rules test", "jsonpad sync-schema --dry-run") or by what it does — which tells the agent how to invoke it. It stops short of saying when to prefer this over get_sdk_method or read_doc, so no explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The limits of each public plan (Free, Indie, Pro, Scale): requests per month and minute, the minimum gap between requests, storage, item size, versions kept, tokens, identities, realtime connections, webhooks and flows. null means unlimited. Sizes are in bytes, rateLimit in milliseconds, prices in GBP.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | One plan, by id or name, e.g. "free" | |
| limit | No | One limit, e.g. maxItemSize |
| Name | Required | Description |
|---|---|---|
| plans | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/non-destructive/non-open-world, so the safety profile is covered structurally. The description adds real semantic context the annotations do not: null means unlimited, sizes are in bytes, rateLimit in milliseconds, prices in GBP. It stops short of describing output shape or any caching behaviour, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, followed by the field enumeration and a compact units/null glossary. The long list of limits is dense but each entry maps to a real enum value, so it earns its place. Slightly list-heavy for a single sentence but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not required, and the description still supplies useful unit and null semantics. With annotations covering the read-only profile and the schema covering both filter params, the definition is essentially complete; only explicit usage/alternative guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the units of the returned values and the null-means-unlimited convention, which directly disambiguates reading the enum limit field values like rateLimit and maxItemSize. It does not state what happens if plan and limit are combined or omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (JSONPad public plan limits) and enumerates exactly what is returned: requests per month/minute, rateLimit gap, storage, item size, versions, tokens, identities, realtime connections, webhooks, flows. This is clearly distinct from the sibling documentation/API-lookup tools and an agent can tell what it gets without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (call it to look up quota/limit values for a plan or a single limit) but there is no explicit when-to-use, when-not-to-use, or alternative routing. An agent can infer intent from the content described, yet nothing tells it how this differs from e.g. get_api_endpoint or lookup_error at call time.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signature, description and example of a method in the JavaScript SDK (@basementuniverse/jsonpad-sdk) or the realtime SDK, and the REST endpoint it calls. Find it by name ("restoreItem") or by what it does.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The method name, e.g. restoreItem | |
| query | No | What the method does, e.g. "wait for an index to build" | |
| package | No | Only one package |
| Name | Required | Description |
|---|---|---|
| method | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, non-destructive, closed-world lookup, so the safety profile is fully covered. The description's only behavioral addition is the list of returned content, which is largely redundant given an output schema exists, and it says nothing about ambiguity, multiple matches, or whether the SDK docs must be indexed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler; the returned artifacts are front-loaded and the lookup instruction follows. Slightly awkward phrasing in the first clause, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and complete annotations, the description only needs to establish what is retrieved and how to search. It does both adequately, though edge behavior for fuzzy/ambiguous queries is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates the name-vs-query distinction already present in the schema and adds no format, matching, or precedence rules (e.g. what happens if both name and query are supplied, or how package narrows results).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (a method in the JavaScript SDK @basementuniverse/jsonpad-sdk or the realtime SDK) and enumerates exactly what is returned: signature, description, example, and the REST endpoint it calls. It is implicitly distinguishable from siblings like get_api_endpoint, get_cli_command and read_doc, which target different artifact types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent the two lookup modes: "Find it by name (\"restoreItem\") or by what it does." That maps directly onto the name/query parameters and gives clear usage context. It stops short of naming an alternative sibling or stating when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the REST API endpoints an API token can use, as method, path and title. Get one in full with get_api_endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| resource | No | Only one resource |
| Name | Required | Description |
|---|---|---|
| endpoints | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the output shape and the token-scoping constraint, which is useful, but nothing about pagination or result ordering. With rich annotations, this is adequate but not additive enough for a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste. The core purpose and the output shape are front-loaded, and the pointer to the alternative tool follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering the safety and mutability profile, the description needs only to explain purpose and routing, which it does. A minor gap is that it doesn't clarify whether the resource enum narrows results or how many endpoints are returned, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole 'resource' parameter has an enumerated description, so the schema already carries the semantics. The description adds no filter syntax or behavior beyond what the schema states, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the REST API endpoints') and scopes it to what an API token can use, plus the returned shape (method, path, title). It also names the sibling get_api_endpoint, so an agent can distinguish this list tool from the detail tool immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: 'Get one in full with get_api_endpoint.' The condition (want full detail on a single endpoint) is clear. It doesn't spell out when-not to use this list tool or mention filtering behavior for the resource enum, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the documentation pages by section, with a description of each: the table of contents.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Only list one section |
| Name | Required | Description |
|---|---|---|
| sections | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that entries include a description of each page, but says nothing about ordering, size, or pagination behavior of the listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence that front-loads the action and the grouping, with the 'table of contents' gloss appended. The trailing colon phrase is slightly awkward but consumes no real space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only listing with an output schema, the description is sufficient: it explains what is returned conceptually and leaves item shapes to the output schema. Nothing critical is missing, though a nod to listing-without-filter behavior would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'section' parameter already carries its enum and the note 'Only list one section'. The phrase 'by section' in the description aligns with the schema but adds no format or scoping detail beyond it, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (documentation pages / table of contents) and notes it is grouped by section with descriptions. An agent can distinguish it from read_doc or search_docs, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: listing is the natural first step before read_doc or search_docs, but the description never states when to use this versus those alternatives or whether the section filter is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a JSONPad API error code means, its HTTP status, and the guides that explain it. Give the numeric code (10013) or the name (QUOTA_EXCEEDED), as found in an error response's "code" and "name".
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | The numeric code, e.g. 10013 | |
| name | No | The name, e.g. QUOTA_EXCEEDED |
| Name | Required | Description |
|---|---|---|
| error | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false, covering the safety profile. The description adds return content and input provenance, but since an output schema exists, this is modest additional behavioral context rather than essential disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences: the first defines purpose and return content, the second gives input forms and provenance. Nothing is wasted and the important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup with rich annotations and an output schema, the description is nearly complete. It leaves one minor ambiguity: with zero required parameters in the schema, it does not explicitly say whether exactly one of code or name is required or what happens if both or neither are supplied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already gives examples for both parameters. The description adds useful semantics by stating that either the numeric code or the name can be supplied and that both come from an error response's "code" and "name" fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (JSONPad API error code) and what it returns (meaning, HTTP status, explanatory guides). No sibling tool handles error lookup, so it is clearly distinguishable from the surrounding documentation and validation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when you have an error response's code or name, but does not explicitly say when to use this tool versus alternatives or when not to use it. The input source is clear, but usage guidance remains inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a documentation page as markdown, or one section of it. Give a page slug ("indexing"), a /docs path, a jsonpad.io URL (with or without .md, and with an optional #anchor), "sdk/jsonpad-sdk", "sdk/jsonpad-realtime-sdk", "cli/reference" or "cli/readme". Long pages are cut at a section boundary; read on with the returned nextSection.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | The page: a slug, path or URL | |
| section | No | A heading anchor ("filtering-items") or heading text; overrides a #anchor in page | |
| maxChars | No | The most characters of markdown to return |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| title | Yes | |
| markdown | Yes | |
| truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds real operational context beyond them: long pages are cut at a section boundary, and nextSection is the continuation handle. It still doesn't say how the section boundary is chosen or what happens with an unmatched section value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior leads and the accepted input list is packed into a single sentence rather than scattered. The enumeration is dense but each item carries distinct information, and the truncation caveat is placed last where it belongs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return shapes need no explanation, and the description correctly focuses on the two things structured fields don't cover: what counts as a valid page reference and how truncated reads continue. Only the routing question (when to use this vs search_docs) remains unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 enriches the 'page' parameter with concrete accepted values ('sdk/jsonpad-sdk', 'cli/reference'), the fact that jsonpad.io URLs work with or without .md and with an optional #anchor. It also reinforces that 'section' overrides an inline #anchor, matching the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read a documentation page as markdown, or one section of it') and enumerates the accepted page forms. An agent can distinguish it from list_docs and search_docs purely from this text, since it is the retrieval-by-identity tool rather than a discovery tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells you what input shapes are accepted and how to continue a truncated read ('read on with the returned nextSection'), which implies usage. However it never states when to prefer this over siblings like search_docs, list_docs, or get_cli_command, and gives no exclusions or prerequisites. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the JSONPad documentation, the JavaScript SDK references and the command line tool reference. Returns the best-matching sections with a snippet and their jsonpad.io URL; read one with read_doc. Exact identifiers work well: error codes and names, headers, SDK methods, CLI commands, $jsonpad-var variables, "POST /lists/{listId}/items".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many results (1-10) | |
| query | Yes | What to look for | |
| section | No | Only search one section: guides, api-reference (every API reference section), lists, items, indexes, identities, tokens, flows, schema-sync, sdk or cli |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses the return shape (best-matching sections with a snippet and jsonpad.io URL) and what query styles succeed. No rate limits or pagination behavior are mentioned, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the scope, then the return shape, then the retrieval hand-off, then query tips. The example list is dense but every item is actionable and nothing is redundant with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no elaboration, and annotations fully cover the safety profile; the description still adds the snippet/URL detail and search-then-read workflow. With 100% schema coverage and all parameters, annotations and output documented, nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the schema already documents all three parameters, making 3 the baseline. The description earns a bump by explaining what inputs work well in 'query' — error codes, names, headers, SDK methods, CLI commands, $jsonpad-var variables and literal route strings like "POST /lists/{listId}/items" — which is meaning the schema's 'What to look for' does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (JSONPad documentation, JavaScript SDK references, CLI reference), and explicitly names read_doc as the follow-up reader. An agent can distinguish this from list_docs, read_doc, get_sdk_method and get_cli_command without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Routes the agent explicitly to the sibling read_doc for retrieval, and gives concrete guidance on query construction ('exact identifiers work well' with examples). It does not, however, state when to prefer lookup_error or get_sdk_method over a general search, so the alternatives coverage is partial rather than exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a schema sync document (sync-v1) as far as possible without an account: against the JSON schema the API uses, the API's rules for keys and indexes, and every rule set and flow in it with their tests. Documents that reference files (rulesFile, flowFile and their tests) are checked too if the files' contents are given in files. What a sync would change needs the account: the API server's plan_schema_sync, or jsonpad sync-schema --dry-run.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | The contents of files the document references, keyed by the path written in the document, e.g. { "rules/games.rules": "allow ..." } | |
| document | Yes | The schema sync document |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| problems | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds meaningful scope context by listing the account-free boundaries and pointing to account-requiring alternatives, which the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that are front-loaded with the core action and then progressively add scope and boundaries. It is dense but each clause adds information; the parenthetical tooling list is slightly list-like but justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with rich annotations, a 2-param schema at full coverage, and an output schema present, the description covers what is validated and what cannot be validated without an account. Return-format details are correctly left to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents 'document' and 'files'. The description adds value by clarifying that document can carry file references (rulesFile, flowFile and their tests) and that those are only checked if the file contents are supplied via files, which is semantic context beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (validate/check) and resource (schema sync document, sync-v1) and enumerates exactly what is validated: JSON schema, key/index rules, rule sets and flows with their tests. It clearly distinguishes itself from sibling checkers like check_flow and check_write_rules by scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It makes the boundary explicit: this checks as far as possible without an account, and directs the agent elsewhere for plan effects (plan_schema_sync, or jsonpad sync-schema --dry-run). That is strong when-to-use routing, though it doesn't name the sibling tools it overlaps with (check_flow/check_write_rules) or say when not to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check an API token's permission rules against the schema the API uses, say which rule shape a broken one was meant to be, and warn about valid rules that probably don't do what was meant (rule order, restore without view, sync-schema alone, allow "*").
| Name | Required | Description | Default |
|---|---|---|---|
| permissions | Yes | The permission rules, e.g. [{ "mode": "allow", "action": "view", "resourceType": "item", "listIds": ["*"], "itemIds": ["*"] }] |
| Name | Required | Description |
|---|---|---|
| ok | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive for this analysis tool, consistent with the description. The description adds genuine behavioral value beyond that: it discloses the specific diagnostic classes surfaced (rule-shape identification, rule-order warnings, 'restore without view', 'sync-schema alone', bare allow '*'), which tells the agent what signal it will get back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the parenthetical list of warning cases is dense but each item is informative. Slightly packed as one long clause, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich annotation set, 100% schema coverage on the sole parameter, and a declared output schema carrying return details, the description does the remaining job: it tells the agent what the validator detects and how it reports broken vs. suspicious rules. Nothing essential to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter exists and schema coverage is 100%, with an inline example of the permission-rule shape already provided in the schema. The description adds no syntax or format details beyond the schema, so the baseline 3 for high coverage is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (validate/check) and resource (token permission rules against the API schema), and further specifies the two classes of output: identifying the intended shape of a broken rule and flagging valid-but-likely-wrong rules. This is specific enough to differentiate it from siblings like check_write_rules and validate_sync_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the purpose (validating an existing token's permission rules), but the description offers no explicit when-to-use trigger, no prerequisites, and does not name check_write_rules or any sibling as an alternative. Guidance is present only by inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_flowcheck_write_ruleseval_write_ruleget_api_endpointget_cli_commandget_plan_limitsget_sdk_methodlist_api_endpointslist_docslookup_errorread_docsearch_docsvalidate_sync_documentvalidate_token_permissionsWrite, organize and publish documentation sites, help centers and SOPs on OpenDocs.cloud.
JSON-RPC & Data API docs, chains, status, CU pricing, error help, API key signup. No key needed.
Create, validate, edit, export (markdown/svg/png/mermaid), and search JSON Canvas files.
Official BlockRazor documentation for sending and receiving transations faster.
Add one secure layer between your agents and this server.
