dot•requirements

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

Annotations only say readOnly=false and non-idempotent; the description goes far beyond them by disclosing immediate team/dotreq visibility, version-1 semantics, validation behavior (malformed dotrequirements blocks reject creation), title derivation from the leading H1, and the returned shareable link. That is exactly the behavioral context an agent needs before a non-reversible write.

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 tight sentences, front-loaded with the verb and the most consequential fact (immediate publication). Minor redundancy with the schema on the H1/title rule, 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?

With no output schema, the description helpfully covers the return value (shareable link), the publication side effects, and the failure mode for malformed blocks. It omits permission/auth requirements for the target project and says nothing about the relationship to the near-identical sibling tool, which is the main remaining 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 coverage is 100%, so the schema already documents both parameters, including the H1-as-title rule and the dotrequirements block support. The description largely restates that, adding only the edge case that an omitted H1 yields an untitled document, so baseline 3 is appropriate.

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 new requirements document') and adds scope details like immediate publication. However, it does not differentiate itself from the very similar sibling 'create-requirement-document', leaving the agent to guess which of the two to call.

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 note that the document PUBLISHES IMMEDIATELY as version 1 implies this is the direct-to-live creation path rather than a draft-then-publish flow, which is useful implied guidance. But no alternative is named (e.g. publish-document, edit-document), and no prerequisites or when-not-to-use conditions are given.

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 only state readOnlyHint=false (a write op). The description adds meaningful behavior: the markup dialect constraint, the JSX-with-fixed-values rule, the prerequisite to read mockup-guide first, and the refusal semantics ('lists every problem with its line — fix them all and retry once'). This is substantial context beyond the annotation.

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 tight sentences, front-loaded with what a mockup is, then the dialect prerequisite, then the attach option and refusal behavior. Every sentence carries information; 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?

For a create tool with no output schema and full schema coverage, the description covers the artifact, the dialect, a prerequisite (mockup-guide), an optional attach behavior, and error handling on refusal. It does not explain the return payload, but no output schema exists so some gap remains regarding success response shape.

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

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

Schema coverage is 100%, so each parameter is already documented. The description adds the cross-parameter behavior of passing 'document' to attach in the same call, which is useful semantic value, but does not add format details beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Create a lofi wireframe mockup'), clarifies the artifact ('a static sketch of a screen or short flow'), and explains its role ('attached to a spec so readers see what the words mean'), clearly distinguishing it from edit-mockup and get-mockup.

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 context: says to fetch mockup-guide before composing, and to pass 'document' to attach in the same call. Does not explicitly name an alternative for editing vs creating, but the create intent is unambiguous against siblings like edit-mockup.

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, so the safety profile is covered. The description goes beyond that by disclosing what the payload contains (template, block syntax, label/key patterns) and the downstream consequence of not calling it, which is genuine behavioral context for a documentation 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 sentences, front-loaded with the tool's output and followed by the usage directive. Dense but every clause carries information; the em-dash enumeration is slightly heavy but not wasteful.

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 read-only, single-parameter guide tool with no output schema, the description covers what is returned, what it is for, and when it must be called. Nothing an agent needs to invoke it correctly is missing.

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

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

There is a single required 'project' parameter with 100% schema description coverage, including a pointer to list-projects and a concrete example. The description adds nothing on parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: it returns the format and this project's conventions for requirements documents, enumerating the template, requirement-block syntax, and label/key patterns. It is clearly distinguishable from create-document, which it explicitly frames as the composing counterpart.

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 instructs 'Call this BEFORE composing a document with create-document,' naming both the alternative tool and the ordering condition. It also supplies the consequence of skipping it (publishing as plain prose with no requirements), so the agent knows exactly when this is required.

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?

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false): it discloses that the edit takes effect immediately for anyone viewing the document, that it is NOT published until publish-document runs, and that old_string must match exactly once as the document currently stands. The live-vs-published distinction is critical behavioral context an agent would otherwise guess at.

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 tight sentences, front-loaded with the operation, then the precondition, then the publish semantics. No filler 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?

With no output schema, the description covers the operation, precondition, and side effects well. It does not state what happens when old_string matches zero or multiple times (failure mode) or what the tool returns, which is a modest gap for a mutation 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 all three parameters, including the exactly-once and whitespace constraints on old_string. The description largely restates that constraint, adding only the 'as it currently stands' framing, which is marginal added meaning. Baseline 3 applies.

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

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

States a specific verb+resource+mechanism: 'Edit a document by exact text replacement.' An agent can immediately distinguish this from edit-mockup (different resource) and from create-document/publish-document (different operations).

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 prerequisites and routing explicitly: read first with get-document, and the edit only reaches repos when publish-document is called. This tells the agent both when to use this tool and which sibling handles the follow-up step.

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 only readOnlyHint=false available, the description carries the behavioral load and does so well: it discloses re-validation of the whole markup, rejection with the validator's errors, that the mockup is left unchanged on failure, that the response is a lean confirmation rather than the markup, and that the change is visible to all viewers.

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?

Four tight sentences, no filler, with the replacement mechanism front-loaded and the workflow/visibility notes sequenced after. Every sentence adds a distinct operational fact.

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?

Despite no output schema, the description explains the return shape (lean confirmation, not the full markup) and the failure behavior, so an agent knows what to expect after calling. Nothing needed to invoke or interpret the call correctly is missing.

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

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

Schema description coverage is 100%, so the schema already defines mockup, old_string, and new_string. The description only reinforces the exact-once match constraint already stated in the schema and the origin of the mockup target, adding little parameter-level meaning.

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 plus the mechanism: 'Edit a mockup by exact-text replacement.' An agent can immediately distinguish this from edit-document (markup editing) and from read-side siblings like get-mockup.

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 to get-mockup for reading the source markup and to show-mockup 'once after a batch of edits when the user should see the result,' which also encodes the batch-then-display workflow. The alternative tools and the conditions selecting them are named.

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 the description adds meaningful behavior beyond that: the read includes unpublished draft state and the result reports how the document differs from its published version. That is genuine added context about what the call returns and its place in the edit/publish workflow.

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 short sentences, front-loaded with the core action and scope, then the workflow relationships. No filler; 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?

With one required param, 100% schema coverage, and no output schema, the description covers what an agent needs: what is returned (current markdown including unpublished), the diff-against-published behavior, and how to obtain a valid document target.

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

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

Schema coverage is 100% with a single documented parameter, so the schema carries the semantics. The description reinforces the target lookup ('find it with list-documents') but adds no format or value details beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Read a document as it currently stands, as markdown') plus a distinguishing scope detail: it includes unpublished work. It does not explicitly differentiate itself from the sibling show-document, which is the closest-looking alternative, so it falls short of a 5.

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

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

Gives strong contextual routing: it is the source edit-document matches old_string against, what publish-document would carry, and points to list-documents for finding targets. No explicit when-not-to-use case, but the alternatives are effectively named.

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, so safety is covered. The description adds genuinely new behavioral context: this read is agent-internal and has no user-visible effect, which is the key trait distinguishing it from presentation siblings. It stops short of describing failure modes for an invalid target, so not a full 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?

Two tight sentences, zero filler. The core read behavior comes first and the routing alternative is placed last where it is most useful as a decision aid.

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?

Even with no output schema, the description says what comes back (title and markup) and that there is no user-facing side effect. For a one-parameter read tool with readOnlyHint, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and there is a single required 'mockup' target parameter, so the schema carries the load. The description implies the parameter identifies a mockup but adds no identifier format, resolution, or scope details beyond the schema.

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

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

States a specific verb+resource ('read a mockup's title and markup') and even scopes what part of the mockup is returned. It explicitly distinguishes itself from the closest sibling, show-mockup, so an agent can select 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 both the positive condition ('for your own reasoning and for composing edits') and the explicit negative/alternative ('Puts nothing in front of the user — use show-mockup to present it'). The when-to-use and when-to-use-something-else are both spelled out.

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 readOnlyHint annotation already covers the safety profile, so the description only needs to add context. It does so by disclosing the shape of the result (which requirements are tested, which aren't, and the percentage) plus the branch-scoping behavior, which matters because no output schema exists to convey the return values.

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 core purpose followed by the optional modifier, with no filler 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 two-parameter read-only tool with no output schema, the description covers purpose, filter, and result content adequately. It could go slightly further by noting scope limits (e.g., how untested requirements are counted or whether coverage is recursive), but nothing critical for invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description's 'optionally filter by git branch' merely restates the branch parameter without adding syntax, defaults, or edge-case behavior, 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?

The description states a specific verb and resource (get aggregate test coverage for a project's requirements) and enumerates what the result contains: tested, untested, and the coverage percentage. This scopes it clearly against the sibling get-requirement-coverage, which is per-requirement rather than aggregate-per-project.

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

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

Usage is only implied by the purpose statement; there is no explicit when-to-use, when-not-to-use, or named alternative despite get-requirement-coverage being a plausible sibling. The branch filter is a parameter detail rather than 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, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape: the requirement plus all children as Given/When/Then/And nodes, which matters since there is no output schema.

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

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

One sentence, front-loaded with the action and the identifier, with the return detail appended. Nothing is wasted and nothing is ambiguous.

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

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

For a two-parameter read tool with no output schema, the description covers what is returned (children nodes) and how to identify the target. It could still note behavior when the key is not found, but it is otherwise sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the pointer to list-projects for the slug. The description's 'e.g. AUTH-1' merely echoes the schema's example, adding no new meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Get a specific requirement by its key') and adds the key-format example ('AUTH-1'), so the agent knows this is a point lookup rather than a list. It does not name the sibling it competes with (list-requirements, search-requirements), so the differentiation is inferred rather than stated.

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

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

The requirement for a known key is implied by 'by its key', which suggests use only when the caller already has an identifier. However, no explicit when-to-use vs. search-requirements/list-requirements guidance or prerequisites (e.g. project slug needed) appear in the description.

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

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

Annotations cover the safety profile (readOnlyHint=true), so the description carries a lighter burden. It adds useful behavioral context by enumerating the returned facts (last tested, branch, test file), which is valuable given there is no output schema. It does not mention permissions or empty-coverage behavior, keeping it short of 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?

A single front-loaded sentence listing the verb, scope, and returned facts with zero filler. Every clause earns its place.

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

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

With no output schema, the description usefully names the key return fields, and the readOnly annotation covers the safety question. Only minor gaps remain (pagination/empty-result behavior), which are low impact for a read-only lookup.

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 (project slug, requirementKey) are already fully documented in the schema, including the hint to find the slug with list-projects. The description adds no syntax or format detail beyond what the schema provides, 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 (Get) and resource (test coverage for a requirement) and enumerates what it returns (last tested date, branch, test file). It is clearly distinct from get-requirement (metadata) and get-project-coverage-summary (aggregate), though it never names those siblings 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 'for a specific requirement' implies the scoped use case, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as get-project-coverage-summary for aggregate coverage or get-requirement for requirement details. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral content: the result is an interview protocol addressed to the agent, the agent must follow it with the user, and writing should happen only at the end. It doesn't need to cover auth/rate limits for a local read, so 4 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?

Three sentences, front-loaded with the purpose, then the trigger, then the behavioral instruction. Every clause adds a distinct constraint (when, ordering, where the spec format lives) 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 no output schema and no parameters, the description must explain what the agent receives and what to do with it, and it does: an interview protocol to conduct with the user, followed by a spec written via create-requirement-document at the end. Nothing needed to invoke or use this correctly is missing.

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

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

Zero parameters, so per the rubric the baseline is 4. Schema coverage is 100% and there is nothing parameter-level for the description to clarify.

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

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

States a specific verb+resource ("Get the greenfield discovery interview protocol") and scopes it to a new product or feature. It also names the sibling create-requirement-document and where that tool takes over, so an agent can distinguish it from the document/requirement siblings without opening a schema.

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

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

Gives an explicit trigger (user starting something new and has not worked out what it should do) plus a timing constraint (BEFORE drafting requirements). It also names the follow-on tool and the condition under which the spec is written, so when-to-use and sequencing are 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 only declare readOnlyHint=true, and the description goes meaningfully beyond that by enumerating the returned fields and flagging the shared-state nuance that unpublished changes may be 'your own edits, a teammate's, or both'. It omits pagination/size limits for what could be a long list, which keeps it from 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?

Two tight sentences, front-loaded with the action, and the return-value detail is packed into a single clause with no filler. Nothing reads as padding.

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

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

With no output schema, the description correctly carries the return-shape burden and covers all four returned attributes. It is nearly complete; only list-size/pagination 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?

Only one parameter, and the schema already documents it at 100% coverage ('its slug (find it with list-projects)'). The description adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource with scope ('List a project's documents') and even characterizes the return by referencing 'its target for the other document tools', which implicitly separates it from get-document/show-document/edit-document. It stops short of explicitly naming a sibling to route away from, 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?

There is no explicit when-to-use or when-not-to-use statement, but the mention that each returned document carries 'its target for the other document tools' implies this is the discovery step before get/show/edit calls. That is implied guidance, not stated 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, so safety is covered. The description adds real value beyond that by disclosing the return shape (project name plus the target value other tools consume) and its role as a prerequisite discovery step. It says nothing about pagination or auth, but for a zero-parameter list this is adequate.

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 short sentences, front-loaded with what it does and framed with the follow-up action. Every sentence carries distinct information with no padding.

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

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

With no input parameters and no output schema, the description compensates by describing the returned fields and their downstream purpose. An agent has everything needed to call it and use 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?

The tool has zero parameters, so the baseline is 4. The description usefully explains that the returned target value is what other tools accept as their 'project' argument, which is semantic context the empty schema cannot supply.

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

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

States a specific verb and resource ('List the dotrequirements projects you can work with') and further clarifies the return contents. It is unambiguously distinct from the document/requirement/mockup siblings, which all operate on sub-resources rather than the project container.

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 an explicit triggering condition: 'Call this first when you don't know the project target.' That is clear context for use. It stops short of naming alternatives or a when-not-to-call case, but no competing project-listing tool exists among the siblings.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context beyond that: it describes the return shape (requirement keys, labels, content). It omits pagination, ordering, or how large results are bounded, so it is solid but not 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?

Three short sentences, front-loaded with the verb+resource, then the return shape, then the calling constraint. No filler; every sentence 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?

There is no output schema, so the description carries the return-value burden and does so reasonably ('summary with requirement keys, labels, and content'). Ordering, limits, and pagination are unstated, which is the only meaningful gap for a simple read 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 coverage is 100%, so the schema already documents the single 'project' parameter, including how to find its slug. The description adds value by clarifying the calling convention: there is no ambient current project, so the project must always be supplied.

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

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

States a specific verb and resource ('List all requirements in a dotrequirements project') and names the return content. It is distinguishable from list-projects and search-requirements, though it never explicitly contrasts itself with search-requirements, which is its closest sibling.

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?

Implied usage is clear from the name and description, and it adds a genuine usage constraint ('the caller names the project explicitly — there is no ambient current project'). However, it offers no explicit when-to-use guidance versus search-requirements for enumerating vs finding requirements.

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 this as a safe read (readOnlyHint=true), so the bar is lower. The description still adds real behavioral value beyond the annotations: it discloses that the environment validates markup and rejects naive Tailwind/HTML output, which tells the agent this is effectively a prerequisite rather than an optional reference.

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 scope are front-loaded in the first sentence, with the usage directive second; nothing is wasted on filler. The second sentence is slightly long, but both clauses (the trigger and the reason) carry information, so the length is largely earned.

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, but the description compensates by summarizing the guide's contents (dialect, component set, discarded style, complete worked example). An agent knows exactly what it will receive and when it must call it, so nothing needed to invoke or interpret the tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool is 4. Schema coverage is 100% anyway, and no argument details are needed or missing.

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

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

Specific verb ('Get') plus precisely scoped resource ('the guide to authoring a wireframe mockup'), and it enumerates what the guide contains (markup dialect, component set, discarded style, full example). It is clearly distinguishable from sibling tools like get-mockup and create-mockup, which operate on actual mockups rather than on authoring guidance.

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 an explicit trigger — 'Call this BEFORE composing your first mockup in a conversation' — and states the consequence of skipping it (markup written from general Tailwind/HTML habits is refused). This is a textbook when-to-use directive with the alternative behavior and its failure mode spelled out.

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 flag destructiveHint=true and idempotentHint=false, but the description adds meaningful context those fields cannot convey: this publishes the WHOLE document including a teammate's unpublished work, and it recommends verifying with get-document first. It stops short of describing the response or whether publishing can be undone, so it doesn't reach 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?

Two sentences, front-loaded with the action and destinations, then the critical side-effect warning. Every clause 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 a single fully-documented parameter, destructive/idempotency annotations, and no output schema, the description supplies everything an agent needs: what it does, where it publishes, the risk of unpublished work, and the pre-check step.

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

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

Schema coverage is 100% and the single parameter's description already says it's the document target found via list-documents. The description reinforces that the whole document is affected but adds no new syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb (publish) and resource (document) and goes further to enumerate the destinations — whole team, dotreq sync, requirement tools — which distinguishes it from siblings like edit-document, get-document, and create-document. An agent can identify exactly what this does 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?

It gives explicit sequencing guidance: 'call get-document first and check what it reports as unpublished,' naming the alternative tool and the condition that motivates it. The warning about carrying unpublished work tells the agent when to be cautious, not just how to call it.

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, so the safety profile is covered. The description adds genuinely useful behavioral scope by naming the searched fields (requirement keys, content, labels), but says nothing about filtering behavior, result caps, or pagination, which matters for a search 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 sentences with zero filler; the search mode is front-loaded and the field scope follows immediately. Nothing could be cut without losing information.

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

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

With no output schema, the description should ideally hint at what a search returns (matching requirements, ordering, result limits), and it does not. It is adequate for invocation but leaves the agent unsure what to expect back or how to page through large result sets.

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 baseline is 3, but the description goes beyond the schema: the schema only says the query is a 'text or regex pattern', while the description clarifies which requirement fields that pattern is matched against (keys, content, labels). That is real added meaning for interpreting the query parameter.

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 specific verb (Search) and resource (a project's requirements) and narrows the search mode to text or regex, so the purpose is unambiguous. It does not, however, distinguish itself from close siblings like list-requirements or get-requirement, leaving the agent to infer which retrieval tool fits.

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 explicit when-to-use guidance: nothing says whether this replaces list-requirements when a text query is available, or when get-requirement is preferred for a known key. The usage is only weakly implied by the words 'by text or regex', and no exclusions or prerequisites are given.

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

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

Annotations only supply readOnlyHint=true, and the description adds real behavioral context beyond that: each call appends a new view to the conversation, so calls are cumulative and non-idempotent in effect. It does not discuss permissions or what happens if the document isn't found, but the key side effect is disclosed.

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?

Front-loaded with the primary action and the rendered format before the usage conditions, with no filler sentences. The second sentence is dense with two conditions and a redirection, but every clause carries routing value.

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 one-parameter read-only display tool with no output schema, the description covers purpose, visual result, timing, frequency, and the sibling alternative — everything an agent needs to select and 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 coverage is 100% and the single 'document' parameter already documents its target and points to list-documents. The description adds no further parameter detail (e.g., accepted identifier format), so the schema does the work and the baseline of 3 applies.

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

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

States a specific verb and resource — present a document as a styled, read-only view inline in chat — and even describes what that view contains (requirement cards with keys, criteria, labels). It explicitly distinguishes itself from get-document, the sibling an agent would most plausibly confuse it with.

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

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

Gives explicit positive triggers (user asks to see, review, or discuss a document; once after a batch of edits) and an explicit negative trigger (not after every small edit). It also names the alternative for a competing need: use get-document when reading content for private reasoning.

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=true, so safety is covered. The description adds non-obvious behavioral context: each call adds a new view to the conversation, and the wireframe is interactive (menus open, links move between screens). However, it doesn't explain what happens if the mockup target is invalid or how rendering failures are surfaced.

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, each front-loading essential information: what it does, when to use it, and the alternative. No filler 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 tool with one parameter and no output schema, the description covers the key behavioral traits and usage rules. It does not explain the 'mockup' parameter format, which would help an agent construct the call correctly, but otherwise it is complete enough.

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

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

Schema coverage is 100% for the single 'mockup' parameter, but the schema description is minimal ('The mockup target'). The tool description implies the parameter is a mockup identifier or reference, but does not clarify the expected format (ID, name, path). With one parameter and full schema coverage, the baseline is 3, but the description adds marginal value by implying the target is something that can be presented. However, it does not compensate for the vague schema 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?

States a specific verb ('Present') and resource ('a mockup'), and goes further by describing the rendering modality (hand-drawn wireframe inline in chat). It explicitly distinguishes itself from get-mockup by naming the sibling and contrasting purposes.

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 states when to use it (user asks to see a mockup; once after completing a batch of edits) and when not to (not per edit). It also names the alternative tool (get-mockup) and the condition that selects it ('for reading the markup for your own reasoning').

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, so the safety profile is covered. The description adds meaningful context beyond that: it is AI-generated feedback judged against a project rubric, and it is meant to run BEFORE creating/editing in a compose loop. It does not state rate limits or the shape of the feedback, but for a read-only check tool this is solid.

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 tightly packed sentences: the purpose leads, the mode guidance follows, and the exclusivity constraint closes. No filler; each sentence carries distinct 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, so the description needn't detail return values, and it conveys that the result is style feedback. Combined with 100% schema coverage and a clear readOnly annotation, the definition is nearly complete; only the precise form of the feedback is left implicit.

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 baseline is 3. The description goes beyond the schema by clarifying the purpose of the two target parameters (compose-time markdown vs published document content) and by adding the mutual-exclusion rule 'provide exactly one of the two,' which the schema does not express.

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 and resource: 'Get AI style feedback on requirements content against the project's style rubric.' An agent can immediately tell this tool produces style/rubric feedback rather than creating or editing documents, which differentiates it from near siblings like create-document and edit-document.

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 explicitly states the two modes ('markdown' for content being composed, 'document' for published content), recommends the pre-save compose loop, and enforces the mutual-exclusion constraint ('Provide exactly one of the two'). The when-to-use for each branch is spelled out with no inference required.

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