Pinto Notes

Search

search

Read-onlyIdempotent

Finds notes. With query: ranked full-text search (words, "quoted phrases", OR, -word), best first, with a snippet. With pattern: like grep, a regular expression (or plain text) matched line by line; output "files" (the matching paths), "content" (matching lines as path:line: text, with context lines) or "count". Names and paths match too. Narrow with path (a folder "Work/", a glob "Work/**/2026*", a note and its sub-notes, an app "Work/Habits.app" to search its code), type, pinned, modified_after/before (YYYY-MM-DD), title_only, sub_notes: false, deleted: true. Pages with limit and offset.

Input Schema

Name	Required	Description
`path`	No	Where to look: a folder, a glob, a note, or an app. Default: everywhere.
`type`	No	Only notes, only app code, or only files (by name).
`limit`	No	Results per page (default 20; lines with output content: 100).
`query`	No	Words to find, ranked.
`offset`	No	Skip this many results (the next page).
`output`	No	With pattern. Default files.
`pinned`	No
`context`	No	With output content: lines shown before and after each match (0-10).
`deleted`	No	Include Recently Deleted. Default false.
`pattern`	No	A regular expression (or plain text) to match line by line, like grep.
`sub_notes`	No	Include sub-notes. Default true.
`title_only`	No	Match names, not text.
`case_sensitive`	No	Default false.
`modified_after`	No	YYYY-MM-DD.
`modified_before`	No	YYYY-MM-DD.

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedOct 13, 2026

addedInput schema / properties / case_sensitive

Added value: +{
+  "description": "Default false.",
+  "type": "boolean"
+}

addedInput schema / properties / context

Added value: +{
+  "description": "With output content: lines shown before and after each match (0-10).",
+  "type": "integer"
+}

addedInput schema / properties / deleted

Added value: +{
+  "description": "Include Recently Deleted. Default false.",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Results per page (default 20; lines with output content: 100).",
+  "type": "integer"
+}

addedInput schema / properties / modified_after

Added value: +{
+  "description": "YYYY-MM-DD.",
+  "type": "string"
+}

addedInput schema / properties / modified_before

Added value: +{
+  "description": "YYYY-MM-DD.",
+  "type": "string"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "Skip this many results (the next page).",
+  "type": "integer"
+}

addedInput schema / properties / output

Added value: +{
+  "description": "With pattern. Default files.",
+  "enum": [
+    "files",
+    "content",
+    "count"
+  ],
+  "type": "string"
+}

addedInput schema / properties / path

Added value: +{
+  "description": "Where to look: a folder, a glob, a note, or an app. Default: everywhere.",
+  "type": "string"
+}

addedInput schema / properties / pattern

Added value: +{
+  "description": "A regular expression (or plain text) to match line by line, like grep.",
+  "type": "string"
+}

addedInput schema / properties / pinned
```
Added value: +{
+  "type": "boolean"
+}
```

changedInput schema / properties / query / description

Previous value: -"Search query."New value: +"Words to find, ranked."

addedInput schema / properties / sub_notes

Added value: +{
+  "description": "Include sub-notes. Default true.",
+  "type": "boolean"
+}

addedInput schema / properties / title_only

Added value: +{
+  "description": "Match names, not text.",
+  "type": "boolean"
+}

addedInput schema / properties / type

Added value: +{
+  "description": "Only notes, only app code, or only files (by name).",
+  "enum": [
+    "note",
+    "app",
+    "file"
+  ],
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "query"
-]
```

First observedOct 9, 2026

TDQS

A4.4/5.0

Behavior4/5

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; the description adds substantial behavior beyond that, including result ranking, snippet inclusion, paging semantics via limit/offset, path scoping forms, and opt-in inclusion of Recently Deleted. It does not describe error behavior for missing/invalid patterns or the combined-use rules for query and pattern.

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?

Front-loaded with the two modes before the filter list, and every clause carries information. It is dense to the point of being a run-on in the filter enumeration, but nothing is redundant with the name or title.

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

Completeness5/5

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

For a 15-parameter, zero-required tool with no output schema, the description covers both modes, all output shapes, scoping, filtering, and pagination. An agent can call it correctly without consulting anything else, with only the no-argument and mode-conflict edge cases unspecified.

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 already 93%, so a baseline of 3 applies, but the description adds real meaning: query syntax (words, "quoted phrases", OR, -word), the three output values and their shapes (paths, path:line: text with context, count), concrete path forms, and the YYYY-MM-DD date format. Only the boolean flags like pinned and case_sensitive are left entirely to the schema.

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?

States a specific verb and resource ('Finds notes') and then breaks the tool into its two distinct operating modes, query-based ranked full-text search and pattern-based grep, which lets an agent distinguish it from siblings like list and fetch. The scope of matching (names, paths, text) is spelled out.

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?

The description effectively explains when to use each mode: query for ranked full-text, pattern for line-by-line regex matching, and conditions for the output parameter ('with pattern'). It does not, however, say when to prefer this tool over list or fetch, nor what happens if neither query nor pattern is supplied.

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

All Pinto Notes tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Search

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources