mentor.energy

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

Annotations already cover the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description usefully discloses that results are pre-filtered to 'verified, available' mentors, but says nothing about pagination, ordering, or empty-result 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?

Two sentences, no filler: the core purpose and its qualifier come first, the return shape second. 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?

With no output schema, the description correctly compensates by listing the returned fields, and the tool is a simple two-parameter read so little else is needed. Minor gaps remain around default result count and ordering.

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 both parameters are documented in the schema, including the default of 10 and examples like 'reservoir engineering'. The description only paraphrases the expertise filter and omits 'limit' entirely, adding nothing beyond the schema — 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?

The description gives a specific verb ('Find') and resource ('verified, available mentors on mentor.energy') and even enumerates the returned fields. It is clearly distinct from the course/blog/lesson siblings by domain, but it never addresses the generic 'search' sibling, which is the one plausible overlap.

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?

'Optionally by area of expertise' implies the one filtering scenario, so usage is inferable. However there is no explicit when-to-use versus 'search', no when-not guidance, and no statement about result breadth or defaults.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the 'published' constraint (unpublished posts presumably unreachable), which is genuine value, but says nothing about behavior for a missing/unpublished slug.

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, no filler, and the resource and lookup key are front-loaded. Nothing could be removed without losing meaning.

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 full annotation coverage and no output schema, the description is nearly sufficient; 'full text' tells the agent roughly what comes back. It stops short of describing response contents (title, author, date, body format) or error behavior.

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% for the single slug parameter, including its provenance and length bounds, so the schema carries the semantics. The description's 'by slug' adds no detail beyond that; 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?

The description states a specific verb ('Get') and resource ('full text of a published mentor.energy blog post') plus the lookup key ('by slug'). 'Full text' implicitly separates it from list_blog_posts/search, though no sibling is named explicitly.

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: an agent infers it should call this once it has a slug. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_blog_posts for discovering slugs).

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the return shape (fields returned, preview/video flags), which is genuinely useful given there is no output schema, but says nothing about pagination, ordering of modules/lessons, or depth 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?

One sentence, front-loaded with the verb and resource, and the field list is compact. The trailing enumeration is slightly run-on but each item carries information an agent cannot get from the annotations.

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, single-parameter tool with no output schema, the description adequately covers what is returned and the safety profile is handled by annotations. The missing piece is the relationship to sibling retrieval tools, which is a minor gap at this complexity.

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 'course' parameter is documented in the schema as an id from list_courses or a title. The description adds no format, resolution, or matching behavior for that parameter, so 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 and resource ('Get a course outline') and enumerates the returned contents (modules, lessons, type, duration, video flag, preview flag, links), which distinguishes it implicitly from get_lesson (single lesson) and list_courses (catalog). It never names those siblings, so the differentiation is left to inference rather than stated.

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 offers no when-to-use guidance, no prerequisites, and does not point to alternatives such as get_lesson for a single lesson or list_courses for discovery. An agent must infer the selection condition from the sibling names alone.

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 this a safe, idempotent read, so the description earns credit for the non-obvious behavioral detail: output varies by lesson tier, with full text/video for previews and only a summary plus sign-in link otherwise. The auth prerequisite is disclosed. It stops short of describing not-found or invalid-course 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?

Two sentences, zero filler, and the most decision-relevant fact (preview vs gated content) is placed immediately after the core action.

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 present, the description must explain return values, and it does so for both content tiers plus the auth requirement. It leaves only edge cases (missing lesson, invalid course) unspecified.

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% for both parameters, including the hint that lesson ids come from get_course_outline. The description adds nothing about accepted id/title formats, so the baseline of 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 ("Get a lesson"), and the follow-on sentences make clear it retrieves lesson content rather than course structure or mentor listings. It does not explicitly name or contrast a sibling, but the name is unambiguous against get_course_outline/list_courses.

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 context (available as a preview, otherwise gated behind a free mentor.energy account) but never states when to call this versus get_course_outline or search. The lesson id source is only mentioned in the schema, not in the description.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: results are restricted to published posts (drafts excluded) and are returned newest-first, which an agent needs to interpret results correctly.

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 with the resource, scope, and ordering, and zero filler. Nothing could be removed without losing 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?

For a two-parameter read-only list tool the description is adequate, but there is no output schema, so the return shape (which post fields come back, whether category filtering is exact-match) is undocumented anywhere. That is a modest but real gap rather than a fatal one.

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 limit (range, default 20) and category documented in-schema, so the baseline is 3. The description adds nothing about either parameter — it never mentions paging limits or category filtering — but does not need to.

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 (published mentor.energy blog posts) with a qualifier for content type and explicit sort order (newest first). It does not explicitly contrast itself with get_blog_post or search, so differentiation from siblings is left to inference.

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 browsing published posts but gives no when-to-use guidance, no mention of alternatives like get_blog_post for a single post or search for queries, and no prerequisites. The 'published' qualifier hints at a scope but does not tell the agent when this tool is the right choice.

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 the read-only, idempotent, closed-world safety profile, so the description's burden is lower. It still adds real value by disclosing the 'published' filter constraint and enumerating the returned fields (title, description, discipline, level, duration, objectives, link), which is the only signal about the shape of the response since 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?

A single front-loaded sentence: verb, resource, scope, then the field list. Nothing is padded, and the trailing enumeration earns its place by standing in for the absent output schema.

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 tool with annotations covering safety and no output schema, the description supplies the needed remainder: the filter semantics ('published') and the return fields. It stops short of noting pagination or ordering, which is a minor gap for a catalogue listing.

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, which is the baseline-4 case. The description correctly signals that the call needs no input, consistent with the empty 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 (List) and resource (published mentor.energy courses), plus the scope and audience (energy professionals: oil & gas, geoscience, engineering). An agent can immediately distinguish this from get_course_outline and get_lesson, which retrieve a single item rather than the collection.

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 word 'published' implies this returns the catalogue rather than drafts or a specific course, which is enough for an agent to pick it over get_course_outline. However, it never explicitly names an alternative or states when not to use it, so usage is only implied.

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, openWorldHint=false and destructiveHint=false, so safety and side-effect questions are covered structurally. The description adds the useful detail that matches come back with links, but says nothing about ranking, truncation, or how the per-type limit interacts with 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 short sentences, zero filler, with the search scope front-loaded and the return shape stated second. Nothing could be cut without losing 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?

For a two-parameter, read-only search tool with no output schema, the description covers what is searched and what comes back. A minor gap remains around result ordering and whether the limit applies per content type, which the schema hints at but the description does not confirm.

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% (both query and limit are documented in-schema with bounds and default), so the baseline is 3. The description's phrase 'by keyword' merely restates the query parameter and adds no syntax, matching, or scoping detail 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?

States a specific verb (Search) plus the three resource types it covers (courses, lesson titles, blog posts) and how matching works (by keyword). That is enough for an agent to distinguish it from list_courses/list_blog_posts, though it never names those siblings to make the contrast 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?

Usage is implied: reach for this when you have a keyword rather than wanting a full listing. There is no explicit statement of when to prefer it over list_courses, list_blog_posts, or get_lesson, and 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.