search_notes

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the hybrid semantic + keyword nature, supported filters, limit default/max, and that it returns a list of results. It does not clarify how query-string filters interact with the dedicated parameters, result ordering, or whether the operation is strictly read-only, though search strongly implies it.

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 description is well-organized, starting with a one-line purpose and then using compact bullet lists for query syntax, arguments, and return value. There is some redundancy between the query-syntax filters and the args list, but the structure is scannable and front-loaded without fluff.

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?

Given the sparse schema and lack of annotations, this description provides enough invocation detail: the required query, optional filters, limit behavior, date formats, and return type. The presence of an output schema reduces the need for a detailed return description. Minor gaps remain around sibling differentiation and filter combination semantics, but the agent can call the tool correctly from this description alone.

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 0%, so the description must compensate for the bare schema. It adds meaningful semantics: query expects search text with optional filter syntax like tag:tagname and title:text, limit has default 10 and max 100, dates are ISO format, and tags/category are additional filters. This goes well beyond the schema field names, though it could be clearer about array behavior for tags and how args combine with query-string filters.

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 opening line 'Hybrid semantic + keyword search across all notes' clearly states the verb, resource, and scope. It is recognizable as a search/retrieval operation, but it does not explicitly differentiate itself from sibling search tools like search_facts or find_similar_notes.

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 implies when to use the tool: whenever a user wants to search notes by semantic or keyword matching, with optional filtering. However, it provides no explicit guidance about when to prefer this tool over alternatives such as list_notes, read_note, or find_similar_notes, nor any exclusions.

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