Fedor Chishchin — AI agents & MCP servers

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

Annotations already declare readOnlyHint, idempotentHint and a closed-world scope, so safety is covered. The description usefully adds that the response is full Markdown text, but says nothing about single-vs-multi language behavior or what happens when a slug is missing.

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 sentence with the output format front-loaded and no 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?

No output schema exists, but the description compensates by naming the return payload (full text as Markdown). Parameters and safety are covered elsewhere, leaving only edge-case behavior unaddressed.

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%: slug has an example ('miamiflow') and language has an enum plus default. The description adds only the slug's provenance, so the baseline 3 applies.

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+resource ('full text of one case study') and even the output format ('as Markdown'), which cleanly separates it from the sibling list_case_studies. The parenthetical '(from list_case_studies)' implies the relationship, though it doesn't explicitly contrast the two tools.

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: the '(from list_case_studies)' note tells the agent where slugs originate, suggesting this is the follow-up to listing. There is no explicit when-to-use/when-not statement or named alternative for other content types (get_post, get_services).

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds useful scope context by listing the actual payload contents (time zone, response time), but says nothing about freshness, rate limits, or authorization needs for a read of dynamic 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?

One sentence with the content list fronted after a clear colon; nothing is padded. Slightly awkward phrasing ('How to hire or contact Fedor:') but 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 single optional-parameter read tool with no output schema, the description adequately covers what will be returned. It could go further by tying the 'languages' item to the language parameter, but an agent has enough 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 description coverage is 100% and the single enum parameter is fully documented in the schema, so the baseline is 3. The description's mention of 'languages' loosely signals multilingual output but adds no format or selection guidance 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?

The description names the resource (contact info for Fedor) and enumerates its contents precisely: contact form, services URLs, time zone, languages, response time. It is distinguishable from siblings like get_services and get_post, though the phrase 'services URLs' creates slight overlap with get_services rather than fully disambiguating it.

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 by the framing 'How to hire or contact Fedor' — the agent can infer this is for retrieving contact channels, but there is no explicit when-to-use statement and no alternatives mentioned (e.g., whether to call get_services for service details).

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the output is Markdown, courses are long, and each concept is rendered as a card containing definition, example, caveat and related concepts.

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, front-loaded with the primary purpose and keying parameter. The second sentence about course length and card structure is dense but earns its place as a size warning for the caller.

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 annotations covering safety and a short two-param schema, the description adequately fills the remaining gap by describing return format and content shape in the absence of an output schema. It does not mention truncation or pagination limits, a minor gap given the stated length of courses.

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 both slug and language are already documented in the schema with an example and an enum. The description only adds the provenance of the slug ('from list_courses'); it says nothing about language selection, which is fine since the schema handles it.

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 ('the full text of one course as Markdown') plus the keying parameter ('by slug'), which cleanly distinguishes it from list_courses and the other get_* siblings. An agent can tell what it retrieves without opening the schema.

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?

Explicitly routes the agent to list_courses as the source of the slug, which is the main prerequisite for calling this tool. No explicit when-not condition or alternative for retrieving course content in another form, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return format (full text as Markdown) and the slug provenance, though it says nothing about behavior for a missing slug, truncation of long posts, or per-language variation.

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 tight sentence with the resource and output format front-loaded and the slug dependency trailing. Every clause earns its place; nothing is padding.

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 two-parameter read tool with no output schema, the description covers what is returned (full post text as Markdown) and how to obtain the required slug, which is enough to call it correctly. Missing only edge-case behavior such as a nonexistent slug or oversized posts.

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 both slug and the language enum fully documented and defaulted in the schema. The description only restates 'by slug' and never mentions the language parameter, so it adds nothing beyond the schema baseline.

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 ('the full text of one blog post'), the lookup key ('by slug'), and the output format ('as Markdown'). It also distinguishes itself from the sibling search_posts by naming it as the source of the slug, so an agent can separate lookup-by-slug from browsing.

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 parenthetical '(from search_posts)' explicitly routes the agent to the sibling that produces the required slug, giving clear preconditions. It stops short of stating when NOT to use this tool (e.g. use search_posts/get_post listing for discovery), so no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the exact return shape (two fixed services, each with a summary and page URL), which matters because no output schema exists.

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?

One tight sentence, front-loaded with the resource and cardinality, and every clause earns its place by describing the return contents.

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 appropriately serves as the return-value contract for this simple read-only tool. It covers content and cardinality; only the language-driven variation in returned text is left unmentioned.

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 single language parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no hint that the returned summary/URL text varies by language.

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 resource (Fedor's two services) and enumerates what each entry contains (summary + page URL), so an agent knows precisely what this tool returns. It is clearly distinguishable from the case-study, post, and contact siblings by content domain, though it never explicitly contrasts itself with them.

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?

There is no statement of when to call this tool versus get_contact_info, get_case_study, or the post tools, and no prerequisites or exclusions. Usage is only implied by the resource it returns.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by enumerating the returned fields (slug, title, summary, URL), which is useful given there is no output schema, though it says nothing about ordering, counts, or the language parameter's effect on results.

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 what is listed, then filters, returns, and the escalation path. No 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?

With no output schema, the description usefully enumerates the returned fields, and the sibling routing closes the main gap. Minor omission: the language option (en/es/ru/zh) is not surfaced in the description, though it is fully documented in the 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%, so both parameters are already documented in the schema. The description restates the focus enum and default but adds no semantics beyond it, and never mentions the language parameter. Baseline 3 applies.

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 (list) and resource (case studies of real systems Fedor built), plus what it returns (slug, title, summary, URL). It is clearly distinguishable from sibling get_case_study, which it names as the full-text alternative.

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?

Gives explicit filter values ('agents', 'mcp', 'other', 'all' with 'all' as default) and routes the agent to get_case_study when full text is needed. The condition that selects the alternative is stated, not inferred.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds real context beyond that: the filter is optional, an empty query lists everything, and the exact return fields are enumerated. It does not mention pagination or result limits, which is the remaining gap.

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, front-loaded with the catalog identity and behavior, then routing, then return shape. The descriptor 'plain-language explainers with a diagram per concept' is mild marketing but does help disambiguate from the blog-post siblings.

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?

No output schema exists, and the description compensates by listing the returned fields (slug, title, summary, level, reading time, URL). Combined with the filter and language semantics, an agent has everything needed to call this 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 baseline is 3. The description adds genuine meaning by stating the query matches words 'in the title and summary' — which fields are searched is not derivable from the schema's 'Words to look for'. The language parameter's effect is left to 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?

States a specific verb and resource (list courses) scoped to a named catalog, and immediately distinguishes itself from get_course for full text. An agent can tell this apart from get_post/search_posts without opening any schema.

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?

Explicitly names the sibling alternative and the condition that selects it: 'use get_course for the full text.' Filtering is framed as optional ('Optionally filter by words in the title and summary'), which sets the default behavior. No explicit when-not beyond the get_course boundary.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, so the description's job is lighter. It adds real value beyond them by disclosing the result cap ('up to 10 matches') and ordering ('newest first'), which the annotations cannot 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?

A single sentence with the search subject, the tag constraint, the result cap and ordering, and the sibling escape hatch. Nothing repeated or wasted; the most decision-relevant information comes first.

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 carries the burden and does supply return shape (count cap, sort order). It is essentially complete for a 3-param read-only search, though it could note that empty results are possible or that an empty query lists newest posts.

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 already 100%, so baseline 3 applies. The description adds marginal meaning by clarifying that only one tag may be supplied and by giving concrete tag examples ('agents', 'mcp'), which helps the agent pick plausible values.

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), resource (Fedor's blog posts), and match scope (words in title and summary, optionally one tag). It also contrasts itself with get_post, so an agent can distinguish it from siblings without opening a schema.

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?

Explicitly routes the agent to get_post 'for the full text,' which tells the agent when to search versus when to fetch. It gives no explicit exclusion or note for the other siblings (case studies, services), so it stops short of full when/when-not coverage.

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