Alkemata Knowledge Gateway

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

Annotations already establish that this is a non-read-only, non-destructive write, so the safety profile is covered. The description adds the hierarchical-placement behavior (content lands near its named parent), which is not encoded in annotations. It remains silent on permissions, duplicate handling, and whether a missing category silently becomes top-level.

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 compact sentence with the placement behavior front-loaded and no filler. It is efficient, though its terseness is part of what leaves the parameters undocumented.

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 7-parameter mutation tool with 0% schema coverage and no sibling differentiation, the description covers only category_name placement. Output schema exists so return values need not be explained, but the meaning of map_id, idempotency_key, language, and the required content fields is missing, as is any guidance against the sibling 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 0% across 7 parameters (map_id, content, summary, language, idempotency_key, title all undocumented). The description clarifies only category_name, leaving six parameters with no semantics anywhere, including the null-defaulted map_id and idempotency_key whose purpose is entirely unexplained.

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 a concrete verb ('Add') and resource ('topic') and specifies placement relative to a parent category, so the agent knows this inserts content into a map hierarchy. It does not, however, differentiate itself from siblings like create_topic_at_position or suggest_connection, leaving the reader to infer the distinction.

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 one explicit conditional rule ('omit category_name for a top-level topic'), which is genuine usage guidance for one parameter. But it never states when to use this tool versus create_topic_at_position, suggest_connection, or the other map-mutating siblings, so routing 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds one useful behavioral constraint — only published content is retrievable — but says nothing about behavior for unpublished/invalid IDs or permissions. 'Through the existing public MCP' adds no actionable context.

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 short, front-loaded sentence with the verb first. The trailing clause 'through the existing public MCP' is filler that does not help an agent decide or invoke, keeping it just short of a 5.

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?

An output schema exists, so return values need not be described, and the tool is a simple read-only single-parameter lookup. Still, the post-vs-page distinction and the meaning of post_id are left entirely unaddressed, leaving a gap the schema does not fill.

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 0% and the single required parameter post_id has no title-level explanation. The description only implies that some identifier of a post or page is needed, without clarifying whether it is a WordPress post ID, how pages vs posts are resolved, or what an invalid ID yields.

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: 'Read a published WordPress post or page'. The singular phrasing and 'get' name distinguish it from the sibling 'alkemata-search-published-content', though the description never explicitly names that sibling or contrasts itself with 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?

There is no statement of when to use this tool, when not to, or which sibling handles the search case. The word 'published' weakly implies drafts are out of scope, but the agent receives no routing guidance at all.

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 and destructiveHint=false, so the safety profile is covered. The description adds only the vague phrase 'through the existing public MCP', which hints at unauthenticated access but never states auth, rate limits, result ordering, or pagination 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?

A single front-loaded sentence with no filler, stating verb and resource immediately. It is efficient, though its brevity is partly the source of the missing detail rather than pure conciseness.

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?

An output schema exists so return values need not be explained, but with 0% schema coverage on three parameters and no usage or behavioral guidance, the definition is too thin for the agent to invoke it confidently with correct arguments.

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 0%, so the description carries the full burden for three parameters. It only vaguely covers 'query' and the post/page distinction (matching the post_type enum) and says nothing about per_page or the defaults, leaving two parameters unexplained anywhere.

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) and resource (published WordPress posts or pages), so the agent knows it is a search over published content. It does not explicitly contrast with the closest sibling, alkemata-get-published-content, but the search-vs-get distinction is reasonably 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?

There is no statement of when to use this tool versus alternatives such as alkemata-get-published-content or search_topics, and no prerequisites or exclusions are given. Usage must be inferred entirely from the name and 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 readOnlyHint=false and destructiveHint=false, so the write/no-destroy profile is covered. The description adds nothing beyond that, notably omitting that publish defaults to true (public exposure) and any auth or idempotency behavior — meaningful for a creation 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?

Two short clauses, both front-loaded with the differentiator first and the routing hint second. No filler, no repetition of the 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?

An output schema exists so return values need no explanation, but for a 14-parameter creation tool with 0% schema coverage the description leaves most parameters and the publish-by-default side effect undisclosed. It is far too thin for the tool's 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 0% across 14 parameters, so the description carries the full burden and fails: only map_id's omission rule is explained. Required fields (x, y, title, summary, content) and impactful defaults (publish, min/max_zoom, idempotency_key, region_id) get no semantic elaboration.

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 ('Create a topic') plus the distinguishing scope ('at exact coordinates'), which cleanly separates it from add_map_content's automatic placement. An agent can tell the two siblings apart without opening either 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?

Names the alternative (add_map_content) and the condition that selects it ('for automatic placement'), and gives a conditional usage rule for map_id. It stops short of stating exclusions or prerequisites (permissions, whether a map must already exist), so it is strong but not exhaustive.

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 and destructiveHint=false, so safety is covered; the description reinforces this by scoping to 'published' posts. It adds nothing about ranking/scoring of 'similar', pagination, or how results are ordered, which are the behaviors that actually matter here.

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 compact sentence with the core action front-loaded, no filler. The trailing 'for study planning' is slightly ornamental, but nothing is wasted.

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?

An output schema exists, so return values needn't be re-explained (and the field list here is largely redundant with it). However, with five parameters at 0% schema coverage and no guidance on alternatives, the definition is too thin for an agent to invoke it confidently versus sibling search 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 coverage is 0% across 5 parameters. The description implies similarity is computed against the required 'title' input but says nothing about how map_id, summary, draft_text, or limit change behavior, leaving four parameters undocumented in both schema and description.

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 ('similar published map posts'), and clarifies the similarity is scoped to published content. It doesn't explicitly differentiate from siblings like search_topics or alkemata-search-published-content, which could also surface related content, so it stops 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?

It states a purpose ('for study planning') but never says when to use this over search_topics or the alkemata search tools, nor any prerequisites or exclusions. The agent is left to infer the selection condition from name similarity 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the topical scope of the guidance (reading rules, proposals, creation rules) and no behavioral detail such as whether it is static documentation or dynamically generated; with annotations in place, a 3 is appropriate.

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 no filler; every clause maps to a distinct guidance domain. Nothing could be removed without losing scope 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?

An output schema exists, so the description need not explain return values. For a 0-param, read-only guidance tool, stating the three covered domains is complete enough, though it could note that it is intended as a prerequisite to the other 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate beyond the schema, and the schema coverage is 100%.

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 makes clear this is an onboarding/guidance tool covering article and map reading, anonymous proposals, and authenticated map creation rules, which distinguishes it from the action-oriented siblings. The opening 'Start here' is a weak verb, but the topical scope makes the purpose inferable 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?

'Start here' gives an explicit directive on when to invoke this tool relative to the rest of the Alkemata workflow. It stops short of naming alternatives or when-not-to-use conditions, but the entry-point framing is strong usage guidance for a 0-param guidance tool.

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 and destructiveHint=false, so the safety profile is covered by structured data. The description adds that this surfaces conceptual content (pending vs published) rather than performing actions, but does not state that the payload is static/configuration data, and the output schema handles return details.

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 action directive ("Start here") front-loaded and the content topics following immediately. No filler or repetition of the name or 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 zero-parameter read-only tool with an output schema and annotation-covered safety, the description supplies enough to call it correctly: when to use it and what it returns. The one small gap is that it does not help the agent choose between this and get_agent_guidance.

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, so there is nothing for the description to disambiguate and the baseline is 4. No parameter semantics are needed here.

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 conveys a specific retrieval purpose and enumerates the content served (canonical endpoint, map ID, and the pending-proposal vs publishing distinction), which is clear enough for an agent to know what it gets back. It stops short of differentiating itself from the similarly-oriented sibling get_agent_guidance, so it is clear but not fully disambiguated.

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?

"Start here" is an explicit, actionable usage directive that tells the agent this is the onboarding entry point. It gives clear positive guidance but names no alternatives or when-not conditions, so no routing to get_agent_guidance or other intro tools is provided.

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 and destructiveHint=false, so safety is covered. The description adds that only *published* objects are returned, a genuine filtering behavior. It omits pagination/result-size behavior and whether out-of-range viewports error, so it adds modest value over the 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?

A single front-loaded sentence naming the action first, then the prerequisite. Zero waste, though it is arguably too terse given the parameter burden it is asked to carry.

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?

An output schema exists, so return-value documentation is rightly omitted. But for a 6-required-parameter spatial query with no schema descriptions, the absence of coordinate-system, zoom, and viewport-boundary semantics leaves meaningful gaps 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 0% across 6 required parameters, so the description must compensate and largely does not. It implies the four bounding coordinates via 'viewport' and explains where map_id comes from, but says nothing about zoom, coordinate units, or ordering conventions. Two of six parameters effectively have no semantic guidance anywhere.

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: returning published objects scoped to a viewport. It also names the data source dependency (map_id from list_maps), which separates it from siblings like list_maps and search_topics. It stops short of explicitly contrasting with search_topics, which also retrieves 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?

Provides a workflow prerequisite ('obtain map_id from list_maps first'), which is useful sequencing guidance. However, it gives no when-to-use condition versus alternatives such as search_topics or alkemata-search-published-content for retrieving published content, leaving the choice implicit.

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 and destructiveHint=false, so the safety profile is covered. The description adds that only 'permitted' blocks are returned, which hints at authorization filtering, but it does not explain access rules, pagination, or revision 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?

A single front-loaded sentence with no filler. It is appropriately short but perhaps too terse given the undocumented parameters.

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?

An output schema exists, so the return values need not be explained, and the read-only annotations cover safety. However, with 0% schema coverage the description should explain revision_id semantics and the scope of 'permitted' blocks; it leaves these gaps.

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 0%, so the description must compensate. It says 'for one topic' but never explains topic_id or the optional revision_id (including what omitting revision_id does), leaving both parameters undocumented.

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 (Return) and resource (permitted blocks, published sources and relationships for one topic). It is clear what the tool fetches, though it does not explicitly differentiate itself from the sibling search_topics or get_region.

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?

No when-to-use guidance or alternatives named. The agent cannot tell when to call get_topic versus search_topics or get_region from this description 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that the response contains steps and branches, and says nothing about behavior for unpublished/missing trail ids or errors — a modest contribution given the low bar set by 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?

A single tight sentence with no filler and the resource named up front. It is efficient, though the brevity comes at the cost of the missing guidance noted elsewhere rather than being optimally sized.

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?

An output schema exists, so return-value documentation is not required, and the tool is a simple read-only lookup with one required parameter. Still, an agent gets no help on the id's origin/format or on failure behavior for unpublished trails.

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 0% for the single parameter, so the description carries the burden — yet it never explains that trail_id identifies the trail to fetch or what form the id takes. "Published learning trail" implicitly qualifi​es the id but is not enough to compensate.

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?

Specific verb ("Return") plus resource ("a published learning trail") and even hints at payload shape ("with steps and branches"). It is clear on its own, but it makes no attempt to distinguish itself from siblings such as alkemata-get-published-content or search_topics.

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?

No when-to-use or when-not-to-use guidance at all. Nothing tells the agent whether this is the right call versus the published-content or topic-search siblings, or what prerequisite (a valid published trail id) is needed.

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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that only published categories are returned and that depth is included, but does not disclose pagination, authorization needs, or map_id default 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?

A single, front-loaded sentence with no wasted words. It conveys the resource, output content, and intended downstream use 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?

The tool is low complexity, read-only, and has an output schema, so return values need not be explained. However, the sole parameter is optional with no schema description and no description explanation, leaving a meaningful gap 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?

There is one optional map_id parameter with 0% schema description coverage, and the description does not explain its format, default null behavior, or what happens when it is omitted. 'On a map' only weakly implies the parameter's role.

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 published topic/category names and depth on a map. It also names the related sibling add_map_content, which clarifies its role, though it does not explicitly distinguish itself from list_maps or search_topics.

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 add_map_content' implies this tool is used to discover valid categories before adding map content. However, it does not explicitly say when to use this versus alternatives or what conditions apply, leaving usage context 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the returned identifiers/bounds are needed for a subsequent write, but says nothing about pagination, scope, or auth. With annotations doing the heavy lifting, a 3 is appropriate.

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 no filler; the purpose and the reason to call it are delivered in one pass.

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?

An output schema exists, so return values needn't be detailed here, and the description still front-loads the key returned fields. For a zero-param read tool this is essentially complete, though a note on scope or ordering would round it out.

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, so per the baseline there is nothing for the description to disambiguate. The mention of 'exact map IDs and world bounds' describes the payload rather than a parameter, which is a slight but harmless reach beyond the zero-arg 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 concrete resources ('exact map IDs and world bounds'), so an agent knows what comes back. It doesn't explicitly name or contrast with a sibling (e.g. list_map_categories), which keeps it from 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?

Gives a temporal usage cue—call this 'before creating content'—which implies the prerequisite relationship to add_map_content. However, it names no alternatives or exclusions, so the guidance is implied rather than explicit.

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 declare readOnlyHint=false and destructiveHint=false, so the write/safe-mutation profile is already covered. The description adds the edit-permission requirement, which is genuine behavioral context, but it says nothing about failure modes (missing permission, duplicate title) or whether the operation is idempotent.

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 no filler or repetition. It is efficient, though arguably terse enough that it trades away useful 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?

An output schema exists, so return values need not be described. However, for a 3-required-parameter mutation with 0% parameter coverage and no guidance on wiki selection, duplicates, or markup format, the description is only minimally adequate.

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 0% and all three parameters (project_id, title, text) are required with no documentation. The description provides no help on what project_id refers to, whether text is Markdown/wiki markup, or any format constraints, so it does not compensate for the coverage gap.

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 ('Create a page in a wiki'), which distinguishes it from siblings like openproject_update_wiki_page and openproject_get_wiki_page. It does not explicitly name those siblings or scope beyond the permission clause, but the action 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 gives one precondition ('where the signed-in user has edit permission'), which is useful context, but it never says when to choose this over update_wiki_page or how to handle an already-existing page title. 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.

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

Annotations state readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds the permission requirement ('signed-in user may add work packages'), which is useful context beyond annotations. However, it doesn't disclose what happens on failure, required scope, or whether the created object is returned, leaving moderate gaps.

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?

Single, short sentence with no waste. Front-loads the action and resource clearly.

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 a mutation tool that has annotations and an output schema, and 0% schema description coverage, the description should explain parameter meanings and any prerequisites. It covers the permission prerequisite but leaves parameters undocumented, making it only minimally adequate.

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 0%, so the description needs to compensate for the four undocumented parameters. It only mentions 'project' implicitly via 'in a project' and doesn't clarify field meanings like type_id, subject, or description. The schema does have types and required fields, but no human-readable semantics; the description barely helps.

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?

Specific verb+resource: 'Create a work package in a project'. Clear what it does and distinguishes from sibling read/update tools (openproject_get_work_package, openproject_update_work_package) by its 'Create' verb, though it doesn't refer to them 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?

The phrase 'where the signed-in user may add work packages' implies a permission prerequisite, hinting at when it will succeed. But there's no explicit guidance on when to use this vs. alternatives or any 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 and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavioral value by disclosing that the read returns lock_version and that this is a prerequisite step for editing, which is exactly the kind of context annotations cannot express.

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 no waste; the purpose and the workflow cue are both front-loaded and 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?

An output schema exists, so return values need not be explained, and the description still calls out the important returned field (lock_version). What is missing is any mention of what happens on a bad or missing id, though that is a minor gap for a simple read.

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 0% and the single 'id' parameter carries no description, so the description is the only source of parameter meaning — and it says nothing about what the id identifies or its format. The parameter is nearly self-evident, which keeps this at baseline rather than lower.

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?

Specific verb+resource: 'Read a wiki page's text and lock_version'. An agent can distinguish this from openproject_list_wiki_pages (plural, listing) by the singular page and the returned text. It stops short of explicitly naming the sibling it is not, so it sits below 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 clause 'before editing it' gives a concrete when-to-use rule tied to openproject_update_wiki_page's optimistic-concurrency workflow, which is the key routing decision here. It does not name the alternative tool or state exclusions, so it is clear context rather than full when/when-not guidance.

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 and destructiveHint=false, so the safety profile is covered without the description. The description adds a real behavioral fact beyond that: the response carries lock_version, needed as input to a later edit. It says nothing about not-found behavior, permissions, or error cases, so it clears the (lower) annotated bar without being 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?

One short front-loaded sentence: verb and resource first, secondary detail (lock_version) second. No filler, though the trailing 'for a later edit' is slightly elliptical phrasing rather than crisp instruction.

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?

An output schema exists, so return values need not be explained, and annotations carry the read-only safety profile. What remains missing is any clarification of the id parameter and any note on failure modes for a read of a specific resource, leaving the definition adequate but thin.

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 0% and the single parameter is a bare untyped 'id' with no description. The description does not clarify whether the id is a work package ID, a global identifier, or a project-scoped identifier, so it fails to compensate for the coverage gap. It only weakly implies the id identifies a work package.

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 (read) and resource (work package), which is enough to separate it from openproject_create_work_package and openproject_update_work_package. It does not, however, explicitly distinguish itself from openproject_list_work_packages or openproject_get_wiki_page, so sibling differentiation is only partial.

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 a later edit' implies the intended workflow (fetch before mutating, presumably to feed openproject_update_work_package), which is genuinely useful implied usage. But no explicit when-to-use condition, no named alternative, and no statement of what to do instead if you only need a list, so this is inferred rather than stated.

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 and destructiveHint=false, so safety is covered by structured data. The description adds genuine value by naming the specific field types returned (project IDs, wiki access flags, work package type IDs), which helps an agent plan downstream calls that consume those IDs.

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 no filler; the most actionable part ('Start here') leads and the payoff (which IDs you get) follows immediately. 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 listing tool with an output schema, the description covers the calling context adequately and needn't explain return values. It is only slightly thin in that it doesn't indicate scope or whether results are paginated or filtered, but the output schema can carry that detail.

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, so per the rubric the baseline is 4. There is no parameter surface for the description to explain, and nothing is missing on this dimension.

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 effectively conveys what the tool yields (project IDs, enabled wiki access, work package type IDs) and frames it as the entry point, which distinguishes it from the sibling create/get/list tools that operate on specific projects. However, it never states the action verb 'list' and relies on the reader to infer that it enumerates all projects rather than fetching one.

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?

"Start here" is an explicit sequencing instruction telling the agent to call this before other OpenProject tools, which is strong contextual guidance. It stops short of naming alternatives or exclusions, so it earns a 4 rather than a 5, but the intended call-order is unambiguous.

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 and destructiveHint=false, so safety is covered. The description usefully adds two behavioral facts beyond the annotations: a 100-item result cap and a wiki-view permission filter. It omits pagination/continuation behavior for beyond-100 cases.

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, with zero filler. Every clause (cap, project scope, permission filter) 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. However, with 0% parameter coverage and no usage guidance, the definition is thin for an agent that must supply project_id correctly and know when to call this versus the sibling getter.

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 0%, so the description carries the full burden for the single project_id parameter. It only implies 'in a project' without specifying the integer format or how a valid project_id is obtained, leaving a real gap.

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?

Specific verb 'List' plus resource 'wiki pages' scoped to a project, which clearly separates it from openproject_get_wiki_page and openproject_create_wiki_page. It does not explicitly name a sibling, so it stops 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 gives no when-to-use guidance or alternatives — it never explains how this differs from openproject_get_wiki_page or when to prefer it. The 'signed-in user may view its wiki' clause is a scope constraint, not usage direction.

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 the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds two things they don't: a hard cap of 50 results and recency ordering, plus the permission requirement on the project. It stops short of explaining pagination or how to retrieve more than 50, which is the remaining behavioral 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?

A single front-loaded sentence with no filler; the result cap and scope constraint appear before the optional filter detail, which is the right ordering for an agent scanning for eligibility.

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 an output schema, the description need not explain returns. However, the query filter semantics and the behavior past the 50-result cap are left unresolved, which are the details an agent needs to call this correctly against a large project.

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 0%, so the description must carry parameter meaning. It maps 'project' to project_id and 'filtering subjects' to query, but 'filtering subjects' is ambiguous about matching semantics (substring vs exact, server-side vs client-side), and it never states that project_id is required.

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 (work packages) with scope qualifiers: up to 50, recent, within a permitted project. This cleanly separates it from the sibling single-item getters and the create/update tools, though it never names an alternative 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: a 'list' tool is understood to be for browsing, versus openproject_get_work_package for a single item. The phrase 'in a permitted project' hints at a permission prerequisite but no when-to-use, when-not-to-use, or alternative routing is stated.

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=false and destructiveHint=false, so safety is partly covered. The description adds genuinely useful optimistic-concurrency context (the write is gated on lock_version being current), but it omits what happens on a version mismatch, whether a token/permission is required, and that 'Replace' overwrites existing page text wholesale — a detail that sits in some tension with destructiveHint=false.

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 mutation and its guard condition with zero filler. Nothing is redundant or padded.

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?

An output schema exists, so return values need not be described. But for a three-parameter mutation with no schema descriptions and no annotations covering failure modes, the description should say what a stale lock_version produces and whether the whole text body is overwritten; those gaps keep it at minimally adequate.

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 0% across three parameters, so the description must compensate and only partly does: it explains that lock_version is a concurrency token that must still be current, which is real added meaning. The other two parameters (id, text) get no clarification of format or scope, leaving most of the parameter surface undocumented.

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 ('Replace') and resource ('wiki page text'), so an agent knows this mutates an existing page rather than creating one. It does not explicitly distinguish itself from the similarly-named sibling openproject_update_work_package, so it stops 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 'only when the supplied lock_version is still current' implies a precondition for use, which is more than nothing. However, it never states what to do when the lock is stale (retry? re-fetch via openproject_get_wiki_page?) nor contrasts this with openproject_update_work_package or openproject_create_wiki_page, leaving routing to inference.

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=false and destructiveHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context — the optimistic-locking requirement to supply the current lock_version — but does not say what happens on a stale lock_version (conflict/error) or which permissions are needed.

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 front-loaded sentence with no filler; the editable fields come first and the lock_version prerequisite follows. It is arguably too sparse for a 5-parameter mutation tool, but nothing is wasted.

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?

An output schema exists, so return values need not be described. Still, for a write tool with 5 parameters at 0% schema coverage, the description omits the id parameter's role, valid status values, and conflict behavior when lock_version is stale.

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 0%, so the schema contributes nothing beyond names and types. The description names three of the five parameters and explains that lock_version must be read first, which is meaningful, but leaves 'id' and 'status_id' semantics (valid status values, project scoping) undocumented.

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 (Edit) with the concrete editable fields (subject, description, status) on a work package, so the agent knows exactly what operation it performs. It does not distinguish itself from close siblings such as openproject_update_wiki_page or openproject_create_work_package.

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 clause 'after reading the current lock_version' functions as a real prerequisite (read before edit), which is useful context. However, there is no statement of when to prefer this over update_wiki_page, nor any exclusion of cases where editing is inappropriate.

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 declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is already covered. The description adds genuinely new behavioral context beyond that: the submission lands in a review queue and produces no public post or task, which is the key side-effect fact an agent needs. It stops short of any permissions, rate-limit, or retry semantics, so it is not a 5.

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 core action and immediately followed by the outcome constraint; no filler or repetition of the title. It is arguably too terse for a 6-parameter write tool, but as pure conciseness and structure it is clean.

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?

An output schema exists so return values need not be described, and annotations carry the safety profile. But for a 6-parameter write tool with 0% schema description coverage, the description leaves all parameter semantics, idempotency behavior of client_submission_id, and the review workflow (what happens after submission) undocumented — significant gaps 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 description coverage is 0% across 6 parameters with 3 required, so the description carries the full explanatory burden and does not meet it. It says nothing about what 'problem' or 'proposed_experiment' should contain, what 'related_targets' references (article/topic SubmissionRefs), or that 'client_submission_id' is presumably a deduplication key. Only a loose mapping from 'project idea' to the required fields is implied.

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 (submit a project idea) plus the governing process (editorial review), and explicitly scopes the outcome: no public post, no task. That negative scoping is exactly what separates it from write-oriented siblings like add_map_content, create_topic_at_position, and publish_study_path.

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 use case (propose rather than publish) via 'never creates a public post or task,' which is useful when-not context. However, it never names an alternative tool or states the condition under which an agent should prefer propose_project over, say, publish_study_path or submit_feedback, leaving routing to inference.

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?

Beyond the readOnlyHint=false / destructiveHint=false annotations, the description discloses meaningful behavior: the operation is atomic, an idempotency_key makes retries safe, the server infers category and position, the new post is appended as the last trail step, and contributor output becomes a draft for review. This adds real context the annotations do not carry.

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 front-loaded with the core atomic action, then moves to procedural guidance, with no filler sentences. It is compact for the amount of behavior it conveys, though the sentence flow is a bit clipped.

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?

An output schema exists and annotations cover the safety profile, so the description needn't explain return values or mutation risk. It covers the workflow, draft state, idempotency, and server-side inference; the remaining gap is that several of the 10 undocumented parameters are never given semantics.

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 0% across 10 parameters, so the description must compensate. It explains the important semantics of related_topics (existing topic IDs placed in learning order, appended last) and idempotency_key, and implies category_topic_id is optional via server-side inference, but leaves map_id, language, trail_title, trail_summary, title, summary, and content unaddressed.

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 (atomically add a study text, related links, and an ordered learning trail) and a clear resource, and it distinguishes itself from siblings by naming find_related_map_topics as a prerequisite. The phrasing is slightly muddled in places (study text vs. trail vs. post), but an agent can identify the operation and its scope.

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 prerequisite and ordering instruction ('First call find_related_map_topics') and notes that contributors produce drafts for review. It does not state when-not to use this versus siblings like add_map_content or create_topic_at_position, so it stops short of full routing guidance.

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 and destructiveHint=false, so the safety profile is clear. The description adds the useful behavioral detail that results are bounded to 100, but says nothing about pagination, rate limits, or response structure.

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, front-loaded with the primary action and scope. Every word earns its place with 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 three undocumented parameters (0% schema coverage), a mutation-free search tool, and an output schema that handles return values, the description is incomplete. It should at least explain the query semantics, the language parameter, and the relationship between limit and the 100 cap.

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 0%, so the schema provides no semantic detail for query, limit, or language. The description mentions 'titles and summaries' (implying query searches those fields) and the 100 bound (clarifying the limit parameter's max), but does not explain the language parameter or default behaviors.

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) and resource (map topics), and clarifies the scope is published titles and summaries. It's clear, but it doesn't differentiate from the sibling 'alkemata-search-published-content' or 'find_related_map_topics'.

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?

No explicit guidance on when to use this tool versus alternatives like get_topic or the alkemata search tools. The only constraint is the implicit bound of 100 responses.

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=false and destructiveHint=false, so the write/safe nature is partly covered. The description adds real value beyond that by stating the feedback is private, goes to editorial review, and 'never publishes content' — a meaningful disclosure about side effects. It omits auth requirements and rate/duplicate-submission 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 short sentences, front-loaded with the action and immediately followed by the key constraint and the non-publication guarantee. Nothing is padded or repeated from 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?

An output schema exists, so return values need not be explained. But for a 7-parameter tool with 0% schema coverage, the description addresses only the target selection and the non-publishing behavior, leaving the category enum, optional metadata fields, and idempotency field entirely unexplained.

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 0% across 7 parameters, so the description carries the full explanatory burden. It only clarifies the article_id/topic_id target ('one published article or topic') and says nothing about category, text, source_url, display_name, or client_submission_id, leaving most parameters undocumented.

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 ('Submit private feedback for editorial review') and clarifies the destination (editorial review), which separates it from publishing-oriented siblings like publish_study_path and propose_project. It stops short of naming any sibling explicitly, so it is clear but not maximally differentiated.

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?

'Provide one published article or topic' implies the expected context of use and constrains the target, and 'this never publishes content' rules out one misuse. However, it gives no guidance on when to choose this over siblings such as suggest_connection or propose_project, leaving selection to inference.

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 declare readOnlyHint=false and destructiveHint=false, so the agent already knows this is a non-destructive write. The description adds genuinely useful context by clarifying that no map edge is persisted, which resolves the ambiguity created by readOnlyHint=false (i.e., it records a pending suggestion, not a live edge). It stops short of describing what happens to the suggestion afterward (moderation/queue/expiry).

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 no filler; the scoping constraint ('never creates a map edge') is placed where it matters. Slightly terse, leaving room for a routing clause, but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and the input schema is rich (nested refs, enums, bounds). The description is adequate on behavior but leaves the when-to-use-this-vs-add_map_content question open, which matters for a mutation-flavored tool.

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 0% across 6 parameters (from, to, relation, rationale, source_urls, client_submission_id), and the description adds no parameter meaning at all. The heavy lifting falls entirely to the structured schema (SubmissionRef, relation enum, rationale length bounds); the description does not compensate for the coverage gap.

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 (suggest a connection) and resource (two published targets), with the 'for review' qualifier that signals it is a proposal rather than a committed change. It distinguishes the action reasonably well from add_map_content, though it doesn't name that sibling 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?

'For review' and 'never creates a map edge' imply this is the non-committal alternative to actually adding map content, so usage is inferable. However, no alternative tool is named and no condition is given for when to prefer a suggestion over a direct edge creation.

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