palinode_search

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the direction is covered. The description adds the key behavioral nuance: results are ranked by semantic similarity, not exact match, and returns excerpts rather than full files by default. It does not reveal details like default daily-file penalization or threshold overrides, but it goes beyond the annotations.

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 two concise sentences that front-load the verb 'Search' and immediately convey purpose and high-level return format. There is no wordy or redundant phrasing, and it earns its place without repeating schema content.

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?

The tool has 12 parameters and no output schema, but the description reasonably scopes what the tool does and the main information needed: it returns relevant excerpts via semantic similarity. It does not describe the default threshold of daily-file handling, but the schema covers those details well. The description lacks a note about the optional full-content mode, but it is sufficiently complete for a search tool given the detailed 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%, and every parameter has a clear property description. The tool description does not add new meaning to the parameters—it only mentions the high-level search categories, which are partially mirrored by the enum values. This matches the baseline of 3 because the schema already 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?

The description clearly states the action (Search), the resource (Palinode memory), and the output (memory file excerpts ranked by semantic similarity). It also enumerates the types of context covered (people, projects, decisions, etc.), which distinguishes it from sibling read/list tools like palinode_read and palinode_list.

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 use for finding relevant context via semantic similarity, but does not explicitly contrast it with sibling tools or state when not to use it. No exclusions or alternative tool names are mentioned, leaving the when-to-use guidance implied rather than explicit.

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