search_postsSearch published MojaLab posts by keyword or natural-language query. Results are ranked by relevance (0–1) using hybrid lexical + semantic matching. Use excerpt_length for longer previews.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 5) | |
| query | Yes | Keyword or question to search for | |
| excerpt_length | No | Max excerpt characters (default 150) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the safety/behavioral burden. It discloses that only published posts are searched and that results are ranked by relevance (0–1) using hybrid matching. However, it omits details like return format, pagination, and read-only status, leaving the agent to infer safe behavior.
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 three short sentences, all meaningful: it states the purpose, the ranking behavior, and a parameter hint. It is front-loaded with the keyword 'Search', and every sentence contributes. No wasted text.
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 search tool with no output schema, the description covers scope, ranking, and parameter usage. It hints at return content via 'previews' and 'relevance (0–1)', but does not explicitly state the output structure. It is complete enough for common use cases.
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?
The schema covers all parameters (100%), so the baseline is 3. The description adds value by explaining that excerpt_length controls preview length ('for longer previews'), and it clarifies query accepts natural language. This goes beyond the schema's dry descriptions.
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 tool searches published MojaLab posts using keyword or natural-language queries, specifying the verb, resource, and scope. It distinguishes from siblings like list_posts (search vs list) and search_all (restricted to posts).
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 usage for searching published posts but provides no explicit alternatives or when-not-to-use guidance. It does offer a parameter tip ('Use excerpt_length for longer previews'), but does not mention when to use search_all instead of search_posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource or action: pages, posts, related posts, site summary, tags, and searches. The only potential confusion is between search_all and search_posts, but their descriptions clearly specify scope (all content vs. posts only), so ambiguity is low.
All tools follow a consistent verb_noun pattern: get_* for single-item retrieval, list_* for collections, and search_* for search operations. There are no mixed naming conventions or vague verbs.
Nine tools is well-scoped for a content retrieval server covering posts, pages, tags, search, and site overview. Each tool provides a distinct function without redundancy or overwhelming count.
The surface covers the core read-only lifecycle for a static content site: retrieving individual pages/posts, listing resources, searching across content, and getting related items. Given the server's purpose is content access, there are no major dead ends or missing operations.