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

With no annotations, the description carries the full burden and does most of it: it discloses the two possible return shapes (custom part only vs. full system prompt including base spec and catalog) and the downstream combinination step. It omits failure modes, input validation behavior, or any side effects, which would round out a no-annotation mutation-free generator.

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?

Purpose and inputs are front-loaded in the first clause, followed by two compact sentences covering the two return modes and the in-code combination step. Every sentence carries distinct information with no restatement of the tool name or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain return values — and it does so precisely for both branches (custom-only vs. full prompt with base spec and catalog). With all parameters documented at 100% coverage and the integration contract spelled out, an agent has everything needed to invoke and consume the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters in depth, including the dataSources catalog semantics and the { source, params } reference rule. The description adds framing ('external data-source catalog') and the behavioral consequence of passing it, but no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Generates a custom MDMA prompt') and enumerates the structured inputs (domain, components, fields, steps) plus the conditional dataSources input. The generative framing clearly separates it from sibling read-style tools such as get-prompt and list-prompt-variants without the agent needing to open a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete integration guidance ('use buildSystemPrompt({ customPrompt }) in code to combine it with the base MDMA spec') and a conditional usage rule (pass dataSources to get the full prompt instead). It never explicitly states when to prefer this over get-prompt or validate-prompt, so it stops short of naming alternatives or 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?

With no annotations, the description carries the full burden and does well: it discloses the fetch target (raw.githubusercontent.com/MobileReality/mdma), that the repo is public (implying no auth), the allowed path whitelist, the 'latest version' semantics, and that content comes back as text. It omits failure behavior for a disallowed or missing path and any size/rate considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the verb and source, then constraints, then the default. No filler. Slightly dense but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by stating the return is raw text content. Path restrictions and branch default are covered. Remaining gap is error/edge-case behavior on invalid paths, which is minor for a read-only fetch 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 100%, so the schema already documents both 'ref' and 'path' including the 'main' default. The description restates the default branch and adds the allowed-path constraint, but adds no format or syntax detail beyond what the schema provides. 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 ('Fetches the latest version of an MDMA documentation file') plus the source location and return format. It implicitly separates itself from get-spec/get-prompt by scoping to documentation files, but never names those siblings explicitly, so differentiation requires a small 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?

Gives real selection context: allowed paths are 'any entry from list-docs, plus any *.md file under docs/ or blueprints/', which routes the agent to list-docs for discovery. Missing an explicit 'use get-spec instead when you need a spec' exclusion, so it stops short of 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?

No annotations exist, so the description carries the full behavioral burden, yet it discloses almost nothing beyond the identity of the resource — no error behavior for an unknown name, no note on caching, auth, or whether the returned prompt is text or a structured object. The fallback-on-unknown-variant behavior is present only in the schema, not the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core purpose, then the conditional variant guidance. Every clause earns its place and nothing is 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?

For a simple two-parameter retrieval tool with full schema coverage and no output schema, the description covers purpose, valid inputs, and the sibling needed for variant discovery. Only the shape of the returned prompt is left unstated, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, including the fallback rule; the description largely restates this with different example variant ids. Baseline 3 is warranted because it adds little beyond the structured field text.

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 ('Returns a named MDMA prompt') and enumerates the three valid names, so the agent knows exactly what it fetches without opening the schema. It also implicitly distinguishes itself from retrieval siblings like get-doc/get-spec by naming the MDMA prompt domain.

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 clear conditional rule: pass variantId only when name is mdma-author, and routes the agent to list-prompt-variants to discover valid ids. There is no explicit when-not/exclusion guidance, but the conditional covers the main decision point.

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?

No annotations are provided, so the description carries the full burden. It discloses that the return is the full spec (unfiltered, complete) and enumerates its sections, which implies a safe read-only retrieval, but it says nothing about size or caching behavior. For a zero-parameter, zero-risk retrieval tool this is adequate but thin.

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 leads with the return value and then lists contents. The nested parenthesis with DataSourceDescriptor and the rows/series/options kinds is dense but every item earns its place as an inventory of the spec.

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 effectively substitutes for one by enumerating the spec's sections, which is the key information an agent needs. For a parameterless reference-retrieval tool this is nearly complete; only the response format/size is 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?

The tool takes no parameters, so there is nothing to document; baseline 4 applies. The description correctly implies no input is needed by describing only the returned content.

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?

Names a specific resource (the MDMA specification) and enumerates exactly what it contains: component types, JSON Schemas, binding syntax, DataSourceDescriptor, and authoring rules. It is distinguishable from get-doc/list-docs by content, though it never explicitly contrasts itself with those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get-doc or list-docs. The agent must infer that this is the reference-spec lookup.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It effectively describes the tool's behavior: it returns a catalog with specific fields (path, title, description) from a public GitHub repository. However, it doesn't mention potential limitations like rate limits, authentication requirements, or pagination behavior, which would be valuable for a read operation.

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 perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does and what it returns, the second explains when to use it. There is zero wasted language or redundancy.

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 operation with no annotations and no output schema, the description provides good context about what the tool returns (catalog with path, title, description) and its relationship to other tools. However, without an output schema, additional details about the return format structure would be helpful for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline would be 4. The description appropriately doesn't waste space discussing parameters that don't exist, maintaining focus on the tool's purpose and usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Returns the catalog'), resource ('MDMA documentation files'), and scope ('available for fetching from the public GitHub repo'). It explicitly distinguishes from its sibling 'get-doc' by explaining this tool is for discovery while 'get-doc' is for fetching specific documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('Use this to discover what docs you can pass to get-doc') and names the alternative tool ('get-doc') for the subsequent action. This clearly establishes the workflow relationship between these two tools.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. While it states what data is returned, it doesn't describe important behavioral aspects like whether results are paginated, sorted, filtered, or cached. It also doesn't mention performance characteristics, error conditions, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a zero-parameter tool and front-loads the essential information about what the tool returns.

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 operation with no output schema, the description adequately covers what data is returned. However, it lacks important contextual information about the return format (array structure, field types), potential limitations (number of packages, sorting), and how this tool relates to sibling tools in the MDMA ecosystem.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't waste space discussing non-existent parameters, though it could theoretically mention that no filtering options are available.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Returns') and resource ('all MDMA npm packages'), including the exact data fields returned (purpose, install command, usage example, category). It distinguishes itself from siblings like 'list-docs' by focusing specifically on npm packages rather than documentation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate versus using 'get-doc' or 'list-docs', nor does it specify any prerequisites or contextual constraints for its use.

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?

No annotations are provided, so the description carries the burden. It implies a safe read-only listing and discloses the return shape, but says nothing about authentication, result size, or whether ordering is guaranteed. Adequate but thin for a listing operation.

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 waste. The purpose and return content come first, and the follow-up call to get-prompt is placed after, which is the right ordering.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description's enumeration of returned fields (id, label, description) is genuinely valuable. Combined with the explicit handoff to get-prompt, an agent has what it needs; only pagination/edge-case behavior is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description does not need to compensate for any parameter 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 (Returns) and a well-scoped resource (MDMA_AUTHOR prompt variants) and enumerates the returned fields (id, label, description). It is distinguishable from siblings like list-docs and list-packages by resource, though it does not explicitly name what it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to the next step: pass the returned id to get-prompt as variantId. That gives clear context for when to call this tool. It stops short of naming exclusions or when not to use it versus related listing tools.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the return shape (warnings for anti-patterns, suggestions for improvements) and, given there is no output schema, that is genuine added value. However it never confirms the operation is non-mutating, states failure/error behavior, or says whether validation blocks anything.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded and the return behavior second. Nothing is redundant, and the second sentence earns its place because no output schema exists.

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 single-parameter, read-style validation tool with no output schema, the description covers both what it does and what it returns, which is most of what an agent needs. It could be fuller on failure modes and on how the prompt input should be sourced.

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 a single parameter and schema description coverage is 100%, so the schema already defines 'prompt' as the custom prompt text to validate. The description adds no format, size, or syntax detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (validates) and resource (custom prompt) and names the standard being checked (MDMA conventions), which distinguishes it from the get-prompt/build-system-prompt siblings. It stops short of explicitly contrasting itself with those siblings, 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?

The description implies usage — call it to check a prompt for anti-patterns — but never states when to use it versus alternatives like get-prompt or build-system-prompt, nor any prerequisites or exclusions. Usage is inferable from the verb but not spelled out.

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