Search and read Karandeep Singh's DevOps and AWS blog: articles and cheatsheets.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 11 tools
Each tool has a clearly distinct purpose: listing tags, cheatsheets, recent posts, searching, reading, getting related posts, random pick, quiz, and command extraction. No two tools overlap in intent, so an agent can confidently select the right one.
Most tools follow a verb_noun pattern (browse_by_tag, list_cheatsheets, read_post, search_posts), but a few deviate slightly: random_post and related_posts are adjective_noun, and quiz_me is verb_pronoun. The overall style is consistent (lowercase with underscores), so it's readable and predictable.
11 tools is well within the ideal 3-15 range and each tool earns its place for a blog server: discovery, reading, cheatsheets, commands, and quiz interaction. The scope is appropriately focused without redundancy.
The surface covers all core blog workflows: searching, browsing by tag, listing cheatsheets, reading posts, finding related content, and testing knowledge. Minor gaps exist, such as no explicit 'get_post_by_id' or 'list_all_posts', but URL-based reading and search adequately cover these needs.
List posts with a given tag (e.g. aws, lambda, cost, aurora). Use list_topics to see all tags.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | A tag name. | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details beyond the obvious 'list posts' – it does not mention return format, pagination, sorting, or effects of the limit parameter. Given the annotations, the description provides minimal additional transparency.
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 consists of two concise sentences. The primary action is front-loaded, and the pointer to list_topics is a useful addition with no wasted words. It is an model of efficient writing.
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 read-only list tool with no output schema, the description covers the core action and gives tag examples, but omits any detail about the 'limit' parameter and does not describe the return structure or whether results are ordered. These are small gaps for a tool of this simplicity, so it is adequate but not complete.
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 description adds meaning to the 'tag' parameter by giving examples and directing users to list_topics for all tags, which compensates for the schema's minimal 'A tag name.' description. However, the 'limit' parameter is completely undocumented in both schema and description, and the description does not clarify its behavior, so compensation is partial.
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 ('List posts') and the resource ('with a given tag'), and provides concrete examples (aws, lambda, cost, aurora). It is specific and distinguishes from list_topics by mentioning that tool for tag discovery, but it does not explicitly differentiate from search_posts or related_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 provides one usage pointer: 'Use list_topics to see all tags.' This helps when the agent needs to know valid tag values. However, it does not state when to prefer browse_by_tag over search_posts or other sibling tools, nor does it give exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Jump straight to a cheatsheet by topic (docker, cloudformation, cost, aurora, kubernetes, …) and get its full text.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Cheatsheet topic or name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the useful detail that the tool returns the full text of the cheatsheet, but it does not disclose behavior for unknown topics, formatting, or any error handling. This is adequate given the annotations but not rich.
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 a single, tightly written sentence that front-loads the action and resource, followed by example topics in parentheses. Every word contributes to meaning, 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?
For a one-parameter, read-only tool with no output schema, the description gives the input semantics and the nature of the return value ('full text'), which is enough for correct invocation. It omits exact topic-matching rules and not-found behavior, but those are minor for such a simple interface.
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% ('Cheatsheet topic or name.'), so the baseline is 3. The description adds value by providing concrete examples of valid topics (docker, cloudformation, cost, aurora, kubernetes) and contextualizing the 'by topic' behavior, which helps an agent choose an appropriate value beyond the bare schema definition.
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 action ('jump straight to... get its full text') on a concrete resource (a cheatsheet) with a topic filter. This makes it immediately distinguishable from sibling tools like list_cheatsheets (which enumerates) and read_post (which returns a post, not a cheatsheet).
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 phrase 'jump straight' implies the tool is for when the agent already knows the topic and wants the full cheatsheet text, but there is no explicit contrast with alternatives such as list_cheatsheets or browse_by_tag. No conditions, exclusions, or 'when not to use' guidance are provided, leaving the decision mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return just the runnable commands and code blocks from the best-matching article or cheatsheet — no prose. Use when the user wants the command, not the explanation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max code blocks to return (default 6, max 12). | |
| topic | Yes | Topic or tool, e.g. docker, kubectl, terraform, psql. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar for extra disclosure is lower. The description adds useful behavioral context by stating the return shape ('commands and code blocks', 'no prose') and that it picks the best-matching article, but it does not explain matching behavior, pagination, or error handling.
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 crisp sentences: the first states the result shape and scope, the second states the usage trigger. No filler, no repetition of schema content, and the most decision-relevant 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 two-parameter read-only tool, this is complete enough: it describes the return payload, annotations cover safety and idempotency, and the schema covers parameters. It could mention what happens when no article matches, but such detail is not essential 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 schema already fully documents the topic and limit parameters. The description adds no parameter-level detail beyond what the schema provides, which makes the baseline 3 appropriate.
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 the exact operation ('Return') and resource ('runnable commands and code blocks from the best-matching article or cheatsheet'), and explicitly says 'no prose'. This clearly distinguishes it from read_post, get_cheatsheet, and related content tools without needing to inspect their schemas.
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 gives an explicit trigger condition: 'Use when the user wants the command, not the explanation.' This is clear and actionable, though it does not name alternatives or state when not to use the tool, leaving some sibling differentiation to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all cheatsheets (quick-reference guides) on the blog.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, and the description does not contradict them. It adds scope context ('all...on the blog') but no additional behavioral details such as return format, ordering, or pagination.
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 a single, front-loaded sentence with no filler. Every word contributes meaning, and the parenthetical definition of cheatsheets adds useful clarity without bloat.
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 zero-parameter listing tool with safety and scope already well covered by annotations and the description, nothing essential is missing. An agent can select and invoke this tool correctly based on the given information.
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?
There are zero parameters, so the input schema fully covers parameter semantics and the description does not need to add detail. Per the rubric, a zero-parameter tool gets a baseline 4.
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 uses 'List' as a specific verb and identifies the resource as 'all cheatsheets (quick-reference guides) on the blog,' which is clear and distinguishes it from get_cheatsheet. It does not explicitly contrast with siblings like list_recent or list_topics, but the collection scope is unambiguous.
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 makes the basic use case evident—when you want all cheatsheets—but gives no explicit guidance about when not to use it or which sibling tools to prefer for related needs. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most recently published posts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 8, cap 20. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior, lowering the burden on the description. The description adds useful behavioral context by specifying that only published posts are included and that the ordering is by recency, which goes beyond the structured 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 a single concise sentence that front-loads the core operation and resource. Every word earns its place, with no repetition of the tool name or extraneous detail.
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 read-only list operation with one optional parameter and a strong set of annotations, the description is complete enough for correct invocation. The agent knows what the tool returns (recent, published posts) and the schema documents the only adjustable input.
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 only parameter, limit, is fully documented in the input schema with its default and cap, so schema coverage is 100%. The description does not add any additional parameter-level meaning, which matches the baseline score for high schema coverage.
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, "List", and a precise resource, "the most recently published posts", which clearly distinguishes it from conceptually different siblings like search_posts, list_topics, and random_post. It does not explicitly name a sibling or contrast approaches, so it falls just short of a 5.
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 phrase "most recently published" implicitly tells an agent this is the right choice when a user wants newest posts, but the description provides no explicit guidance about when to prefer alternatives such as search_posts, browse_by_tag, or related_posts. There is no exclusionary language or mention of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every tag on the blog with a post count, for discovering what's covered.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive safety profile. The description adds useful behavioral detail by specifying the output includes a post count and that it lists every tag, implying no filtering. It does not mention ordering or response format, but these are minor for a zero-parameter read-only tool.
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 that names the resource, the output detail, and the intended use case without filler. Every clause earns its place.
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 zero-parameter, read-only listing tool, the description is complete: it states scope ('every tag'), output ('with a post count'), and use case ('discovering what's covered'). No output schema exists, but the description adequately conveys the return shape for an agent to select and invoke 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?
The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to add. Baseline for a 0-parameter tool is 4, and no parameter explanation is needed.
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 clear, specific action: lists every tag on the blog with a post count, and 'for discovering what's covered' explains intent. This distinguishes it from sibling list tools like list_cheatsheets and list_recent.
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 phrase 'for discovering what's covered' implies when it should be used, but the description offers no explicit contrast with siblings such as browse_by_tag or search_posts, and no when-not-to-use guidance. Usage context is present but left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test the user's knowledge with real multiple-choice questions written for the blog's articles. Returns questions, options, and an answers section with explanations. Ask the questions first, then reveal the answers.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many questions (default 3, max 10). | |
| topic | No | Topic to be quizzed on, e.g. aurora, lambda, docker. Omit for a random quiz. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, indicating a safe, read-only, repeatable operation. The description adds valuable context about the interactive flow: 'Ask the questions first, then reveal the answers' and the return structure (questions, options, answers with explanations). This goes beyond the annotations and helps the agent understand the tool's behavioral contract, satisfying the high bar.
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 with no filler. The purpose is front-loaded, return content is immediately specified, and the usage pattern is given in the final sentence. Every sentence earns its place, providing essential information efficiently.
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 tool with two optional parameters and no output schema, the description is quite complete: it covers what it does, what it returns, and how to run the quiz. It doesn't explicitly mention parameter defaults (count default 3) but those are in the schema. A minor gap is lack of examples, but not critical given the simplicity. Overall, adequate for an agent to call it correctly.
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 both parameters (count and topic) are documented in the input schema with descriptions. The description adds no extra parameter semantics beyond what the schema provides, but it does mention 'topic' implicitly by referencing blog topics. Since schema does the heavy lifting, baseline 3 is appropriate.
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 clear verb ('Test the user's knowledge') and resource ('real multiple-choice questions written for the blog's articles'), distinguishing it from read/post tools by emphasizing interactive quizzing. It doesn't explicitly name a sibling alternative, but the purpose is unambiguous among the listed siblings.
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 this tool: when testing knowledge with interactive questions, as opposed to reading posts or listing topics. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a random post from the blog — a surprise pick.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the random-selection behavior, but does not explain how randomness works, whether results may repeat, or what a caller should expect beyond a post. This is acceptable for a simple tool but adds limited behavioral detail.
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 a single front-loaded sentence that communicates the core behavior immediately. The 'surprise pick' clause adds tone and context without unnecessary bulk, so every word earns its place.
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 zero-parameter, read-only tool with full annotation coverage, the description is essentially complete: an agent knows what the tool does and that it is safe to call. It does not specify the output format, but 'Return a random post' gives enough grounding for a no-input utility.
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 tool has zero parameters and the schema is complete, so there are no parameter semantics to document. The description appropriately needs to say nothing about inputs. A baseline of 4 applies because no parameters exist.
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 action ('Return') and resource ('random post from the blog'), clearly distinguishing this from siblings like read_post, search_posts, and list_recent. The 'surprise pick' phrasing reinforces the tool's unique random-selection purpose without being tautological.
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 'surprise pick' wording implies use for serendipitous discovery, but the description does not explicitly state when to use this tool versus the many sibling tools. No exclusions or alternative comparisons are provided, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a post's full text by URL, paginated. Returns a window of characters; call again with the returned next offset to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Post URL or path, e.g. /posts/aurora-postgresql-setup-guide/. | |
| offset | No | Character offset to start from (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds valuable behavioral detail beyond the annotations: results are paginated into character windows and the consumer must call again with the returned next offset to continue.
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 with no filler. The main behavior is front-loaded in the first sentence, and the continuation mechanism is stated plainly in the second. Every sentence earns its place.
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 read tool with strong annotations, the description is nearly complete: it states what is returned and how to paginate. The only minor gap is the absence of an explicit end-of-document condition, like what happens when there is no next offset, but the pagination explanation is sufficient for an agent to call the tool effectively.
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%, giving a baseline of 3. The description adds meaning beyond the schema by explaining how url and offset work together in a pagination loop: each call returns a window and a next offset to continue. This is essential for correct usage that the raw schema alone 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?
The description opens with a concrete verb-object pair: 'Read a post's full text by URL', which specifies exactly what the tool does and what it operates on. The pagination note distinguishes it from sibling tools that discover or list posts rather than retrieve full content.
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 the tool is for reading content when a URL is already available, but it never explicitly says 'use this when' or contrasts it with alternatives like search_posts or related_posts. The context is inferable but not stated as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Karandeep Singh's blog (DevOps/AWS articles and cheatsheets). Returns ranked cards with title, URL, tags, date, reading time, and summary.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 8, cap 20). | |
| query | Yes | Search terms, e.g. 'aurora failover' or 'lambda cold start'. | |
| section | No | Optional: restrict to 'posts' or 'cheatsheets'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is to add context. It does this by specifying the search scope and stating that results are ranked cards containing title, URL, tags, date, reading time, and summary—important because no output schema is provided. This discloses the result contract without repeating annotation data.
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 the purpose front-loaded and the result shape in the second sentence. No filler or redundant restatement of the tool title.
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 read-only search tool with a full schema and annotations, the description covers the main missing piece—output format—since there is no output schema. It doesn't address when to prefer a sibling tool, which is a minor completeness gap for an ecosystem with ten similarly scoped tools.
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 the schema already explains query, limit, and section, including defaults, cap, and enum values. The description adds no additional parameter-level meaning beyond the schema, so it meets the baseline for high schema coverage.
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 uses a clear verb-resource pair ('Search Karandeep Singh's blog') and specifies the content scope (DevOps/AWS articles and cheatsheets) plus the returned card fields. It doesn't explicitly distinguish search_posts from sibling tools like browse_by_tag or related_posts, though the name and search semantics make the distinction inferable.
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 gives no guidance on when to use search_posts versus alternatives such as browse_by_tag, list_recent, or list_topics. It only implies search usage through the verb and the required query parameter; there are no exclusions or condition-based routing.
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.
browse_by_tagget_cheatsheetget_commandslist_cheatsheetslist_recentlist_topicsquiz_merandom_postread_postrelated_postssearch_postsSearch Umesh Malik's blog, fetch posts as Markdown, list topics, get his profile.
Search and read Vector Panda docs: API operations, pricing, storage tiers, measured benchmarks.
Search and read the Radixia blog (enterprise AI, cloud, open source) via MCP.
Search 1,673 source-linked exam blueprints with reviewed guidance. Read-only; no API key.
Add one secure layer between your agents and this server.
