Read-only search of mikereams.com: CSDM diagrams, posts and the Architect's Toolbox
Scored across 4 tools
The four tools target distinct actions (single-page read, two typed listings, and a keyword search), so an agent can generally pick correctly. There is mild overlap between search_site and the list_* tools since search can return diagrams, but the retrieve-one vs. list-all vs. find-matching distinction keeps them mostly separate.
All four names follow a clean verb_noun snake_case pattern: get_page, list_diagrams, list_toolbox, search_site. The convention is uniform and self-explanatory with no deviations.
Four tools is a compact but sensible surface for a personal content site covering reading, search, diagrams, and a toolbox. It is on the lean side but each tool maps to a real content type rather than being filler.
Read, search, and listing for diagrams and toolbox are covered, which handles most visitor workflows. The gap is that writing posts and work items have no dedicated list/browse tool, so enumeration is only possible indirectly via search_site.
Read one public page (a post, work item, diagram, /about or /toolbox) as Markdown, with its canonical URL. Pass a path such as /writing/ or a full mikereams.com URL.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path or https://mikereams.com URL of the page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the word 'public' is consistent with the closed-world hint. Beyond that the description adds little behavioral context: it does not say what happens for a non-public, private, or nonexistent path, nor whether content is truncated for large pages.
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, front-loaded with the core action and page scope, then the argument format. No filler or repetition of the 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 single-parameter read tool with no output schema, the description covers purpose, scope, and input format, and even sketches the return ('as Markdown, with its canonical URL'). It is only missing edge-case behavior such as errors for unknown or non-public paths.
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% for the single parameter, so the baseline is 3, but the description goes slightly beyond the schema's terse 'Path or https://mikereams.com URL of the page' by giving a concrete example path shape ('/writing/<slug>'), which helps the agent construct a valid value.
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 specific verb and resource ('Read one public page') and enumerates the page kinds it returns (post, work item, diagram, /about, /toolbox), which clearly distinguishes it from the list_* and search_site siblings. It never names those siblings, so the differentiation is implicit rather than explicit.
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 tells the agent what to pass ('a path such as /writing/<slug> or a full mikereams.com URL'), which is usable context, but gives no when-to-use routing such as 'use search_site to discover a path, then call get_page to read it' versus the list_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the reference diagrams, including the CSDM models drawn in Blueprint Modeler, with each one's summary, page, downloadable model file and Open-in-Blueprint-Modeler link where there is one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses what each returned item contains (summary, page, downloadable model file, and an Open-in-Blueprint-Modeler link when available), which is critical since there is no output schema.
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 packs the resource and the return payload without filler. The trailing 'where there is one' qualifier is slightly awkward but adds a real nuance about optional links.
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?
With no output schema, the description usefully enumerates the fields returned, and annotations cover the safety semantics. It is complete enough to call correctly, though it omits any hint of ordering, pagination, or volume of diagrams.
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 accepts zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies; no parameter syntax or meaning is needed or missing.
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 and resource ('List the reference diagrams') and even scopes the content to CSDM models drawn in Blueprint Modeler. It does not explicitly distinguish itself from siblings, but get_page/list_toolbox/search_site are far enough in kind that confusion is unlikely.
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?
Usage is only implied: a parameterless enumerator of all diagrams. There is no statement of when to reach for this versus a search or page-fetch tool, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find tools, methods and learning resources from the Architect's Toolbox Guide, filtered by architecture role, kind or keyword. Returns access and license notes and a link to each entry's details and sources.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | tool, method or learning | |
| role | No | Architecture role | |
| query | No | Keyword in the name, publisher or summary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds that results include access/license notes and a detail link, which is useful behavioral context, but does not cover pagination or result limits.
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, front-loaded with the core action and filter dimensions, then the return shape. Minimal waste, though slightly wordy in the second clause.
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 three-param, fully optional, fully documented read tool with annotations covering its safety profile and no output schema, the description supplies enough to call it correctly, including what results contain. Minor gap in alternative routing.
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% with two enum-constrained parameters, so the schema already documents the filter fields. The description restates role/kind/keyword without adding matching syntax, defaults, or semantics beyond the schema.
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?
Clear specific verb (list/find) plus resource (Architect's Toolbox Guide entries), and the three filter dimensions are named. It does not explicitly contrast itself against siblings like get_page or search_site, so it falls 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 description implies the usage context (filtering the Toolbox Guide by role, kind or keyword), but it offers no when-to-use or when-not-to-use guidance, nor does it name alternatives such as search_site for broader lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Mike Reams's posts, work items and diagrams by keyword. Returns titles, one-line summaries and canonical URLs, best match first.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Limit to one kind of page | |
| limit | No | Maximum results (default 10) | |
| query | Yes | Keywords, e.g. 'CSDM application service' or 'AI governance' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, destructive=false and openWorld=false, so safety is covered. The description adds genuinely new behavioral context: the return shape (titles, one-line summaries, canonical URLs) and result ordering (best match first), which the annotations do not convey.
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 tight sentences with zero filler; the search action is front-loaded and the return/ranking detail follows. Every clause carries information.
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?
There is no output schema, so the description sensibly covers what comes back (titles, summaries, canonical URLs) and ordering. Minor omissions remain – no mention of empty-result behavior or pagination beyond the schema's limit bounds – but nothing needed to call the tool correctly is missing.
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% – each parameter has its own description including examples ('CSDM application service') for query, a default for limit, and an explanation of the type enum. The description's 'by keyword' phrasing adds only marginal meaning over that baseline, so a 3 is correct.
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 specific verb (Search) plus the indexed resource set (posts, work items, diagrams) and the mechanism (by keyword). The keyword-ranked, multi-type scope implicitly separates it from get_page (single-page retrieval) and list_diagrams/list_toolbox (unranked enumeration).
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?
Usage is implied rather than stated: keyword search is the obvious fit when you don't already know the page, and get_page is the alternative when you do, but neither the alternative nor a when-not condition is named. No exclusions or prerequisites are given.
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.
get_pagelist_diagramslist_toolboxsearch_siteSearch 1,673 source-linked exam blueprints with reviewed guidance. Read-only; no API key.
Read and search public RegusciLabs information about AI, hardware, POCs, discovery and project work.
Public read-only MCP for products, frameworks, guides, methodology, and blog metadata.
Read-only AgentiScript concept search, catalog, authenticity, license, and approved asset discovery.
Add one secure layer between your agents and this server.
