Entalpa Requirements MCP

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful chaining fact that a snapshot_id is returned and consumed by diff/restore, but says nothing about limits, naming collisions, or permissions required.

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, with the core action front-loaded and the follow-up routing second. Nothing needs to be trimmed.

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 covers the action plus downstream chaining. What remains missing is idempotency/uniqueness behavior for snapshot names, which matters 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%, including descriptions for the nested snapshot name/description fields and project_id, so the schema carries parameter meaning on its own. The description adds no syntax, format, or constraint details beyond that, making the baseline 3 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?

The description states a specific verb and resource: 'Save a snapshot of the project's current state.' An agent can distinguish this from get_project_snapshot, projects_list_snapshots, and restore_project_snapshot without opening any schema.

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

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

It explicitly routes the agent forward, naming projects_diff as the consumer of the returned snapshot_id and restore_project_snapshot as the restore path. It does not, however, say when to create a snapshot versus just relying on existing snapshots or what preconditions exist.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that the response includes the project state captured at snapshot time, which is useful context, but says nothing about failure modes (e.g., unknown snapshot_id) or whether the snapshot content is static.

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 efficient sentence with no filler, front-loaded with the verb and the scope of what is returned. It is appropriately sized for a simple two-parameter read tool.

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 in prose, and annotations cover the read-only/idempotent nature. What remains is minor: no mention of behavior when the snapshot does not exist or belongs to another 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 100% with two UUID parameters fully documented in the schema, so the description need not restate them. It adds no extra meaning about how project_id and snapshot_id interact, 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 (Get) and resource (a saved snapshot's full detail), making it clearly distinct from projects_list_snapshots and create_project_snapshot. It does not explicitly name a sibling, but 'full detail' implicitly contrasts with list-style tools.

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

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

Usage is only implied: the agent can infer this is the tool to call when it needs a snapshot's complete contents rather than a list. There is no explicit statement of when to prefer this over projects_list_snapshots or restore_project_snapshot, and no prerequisites noted.

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 safety profile is partly covered. The description adds nothing beyond that: it does not say whether creation is idempotent, what happens on duplicate interfaces, whether the new contract is locked by default, or what identifiers come back. For a create tool with nested objects and an explicit 'lock' flag, meaningful behavioral context is missing.

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

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

A single front-loaded sentence with zero filler, so nothing needs trimming. Its brevity is efficient rather than padded, though it is arguably too thin to earn a top score on structure.

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 output schema exists, so return values need not be explained, and the 100%-covered input schema documents fields. Still, for a creation tool over two subsystem references with nested metadata, the description omits any notion of required prior state, duplicate handling, or how the interface is scoped to the project, leaving a noticeable 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 the rich nested schema (source/target subsystem ids, interface_type enum values DATA/TRIGGER/STATE, description_payload, lock, content metadata) already carries full parameter meaning. The description adds no format, constraint, or payload-shape guidance beyond it, 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 gives a specific verb+resource ('Create an interface contract') and adds scope ('between two subsystems'), which is enough to distinguish it from interface_contracts_update, interface_contracts_patch, and interface_contracts_get just by name. It does not, however, explicitly contrast itself with any sibling, so it lands at 4 rather than 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?

There is no guidance on when to use this tool versus interface_contracts_update or interface_contracts_patch, and no prerequisites are stated (e.g. that project_id and both subsystem UUIDs must already exist). The agent must infer usage entirely from the verb.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds nothing beyond the action itself: it does not say whether the deletion is permanent, whether it cascades to related items, or whether confirmation/auth is required.

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 waste. It is efficient but arguably too terse to convey the destructive semantics the caller should be aware of.

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 low-complexity 2-param tool with an output schema (no need to describe return values) and annotations covering the destructive profile, the description is adequate. It leaves only minor gaps around reversibility and cascade behavior.

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

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

Schema description coverage is 100%, so both parameters (project_id, interface_contract_id) are already fully documented in the schema. The description's 'by UUID' mirrors rather than extends 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 (delete) and resource (interface contract) plus the identifier used. It is clear what the tool does, though it does not explicitly distinguish itself from the update/patch siblings, which also mutate a single contract.

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 (e.g., update vs. delete, or how to locate the UUID first). The agent must infer selection from the name 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, idempotentHint=true, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — no mention of not-found behavior, permissions, or lookup semantics — so it contributes essentially nothing new.

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 zero filler, and the identifying parameter ('by id') appears immediately. Nothing in the sentence is redundant with 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?

With an output schema present, annotations covering the safety profile, and full parameter documentation in the schema, the description does not need to explain return values. For a simple UUID-keyed get, it is nearly sufficient, though it omits any note about missing-record behavior.

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

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

Schema description coverage is 100%, with both project_id and interface_contract_id documented as UUIDs in the schema, so the baseline is 3. The description adds no syntax or constraint detail beyond what the schema already provides.

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 an interface contract by id'), which cleanly separates it from the create/delete/list/patch siblings in the same family. It does not explicitly name or contrast against those siblings, 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?

There is no guidance on when to use this tool versus siblings like interface_contracts_list or interface_contracts_get_many-style alternatives, and no prerequisites or exclusions are stated. Usage is only implied by the word 'Get' and the required id parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that—no pagination behavior, ordering, filtering, or result-size context—leaving meaningful behavioral gaps for a list endpoint.

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 zero waste. It is efficient, though the extreme brevity leaves little room to convey anything else, so it is not maximally informative.

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 an output schema present, return values need not be described, and the single required parameter is fully covered by the schema. However, for a list tool the description omits any indication of pagination, filtering, or result scope, so it 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 100% and the single project_id parameter is fully documented as a project UUID in the schema. The description adds no syntax or format detail beyond it, 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 clear verb ('List') and resource ('interface contracts') scoped to a project, which is enough to distinguish it from the singular interface_contracts_get and the create/delete/update siblings. It is specific but does not explicitly name or contrast an alternative, 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 context and never mentions the alternative of retrieving a single contract via interface_contracts_get. An agent must infer usage purely from the tool name.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. However, the description adds nothing of its own — notably it never explains patch semantics (partial/merge vs replace) or what happens to omitted fields, which is the single most important behavioral distinction of a patch 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?

A single four-word sentence is structurally clean and front-loaded with the verb, but here brevity reflects under-specification rather than discipline. It is not padded, so it avoids a lower score.

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?

Given a nested patch payload, 100% schema coverage and the presence of an output schema, the description still owes the agent the patch-vs-update distinction and merge behavior. One sentence is inadequate for a mutation tool with this schema complexity.

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

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

Schema description coverage is 100% and the schema documents all three parameters, including the nested patch object and its ignored generated keys, so the schema carries the load. The description contributes zero additional parameter meaning, making the baseline 3 correct.

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 is a verbatim restatement of the tool name and title ('Patch an interface contract'), which the rubric defines as tautology. It gives no indication of what distinguishes this from interface_contracts_update or requirements_patch.

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 when-to-use guidance, no statement of prerequisites, and no mention of the alternative tools (interface_contracts_update, requirements_patch) an agent should weigh against it. The agent is left to infer everything from the name 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 only declare this is a non-read-only write, but the description adds the crucial behavioral trait that omitted flags and lock are RESET by a PUT and must be re-sent to be preserved. That data-loss warning goes well beyond the structured fields and is exactly the kind of context that prevents an agent from silently wiping 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?

Three dense sentences, front-loaded with the operation, then merge behavior, then the reset warning, then the alternative. No filler; every sentence carries actionable information for a nested-object tool.

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 description covers the tricky write semantics for this nested-payload update. Auth/permission expectations are unstated, but for this complexity the description is sufficient to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description exceeds it by explaining the merge semantics of 'content' (send only changed keys, arrays for metadata) and which fields a PUT requires. It adds real meaning beyond the field-level schema descriptions.

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 ('Update an interface contract') and immediately distinguishes the operation from its closest sibling by steering partial edits to interface_contracts_patch. An agent can tell this apart from the PATCH variant 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?

'Prefer interface_contracts_patch for partial edits' names the alternative and the condition that selects it, which is strong routing guidance. It stops short of explicitly stating when a full PUT (as opposed to a patch) is the right choice, leaving that condition 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 only declare readOnlyHint=false and destructiveHint=false. The description adds genuinely behavioral context beyond that: supplying an answer marks it answered, and answered/dismissed states are never overwritten by regeneration. It doesn't state what happens if the question ID is stale or invalid, but the persistence guarantee is a meaningful disclosure an agent cannot get from 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?

Two sentences with zero padding; the core action is front-loaded and the second sentence carries only the non-obvious persistence rule. 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 explained, and annotations cover the safety profile. The description supplies the one thing an agent would otherwise have to guess — that answers are durable across regeneration — though it says nothing about error or invalid-id behavior for a required-UUID mutation.

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 answer, status, project_id and open_question_id. The description restates the answer/answered linkage that is already in the answer parameter description, adding no new syntax, format or constraint information. 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 pair (answer/dismiss) and a specific resource (an open question), and the second sentence clarifies the two outcomes. It does not explicitly differentiate itself from siblings like open_questions_list or open_questions_convert_to_story, but the mutation semantics are 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 implies the usage context (resolving an open question raised earlier in elicitation) and notes that the answer feeds back into later elicitation, but it never states when to use this versus convert_to_story or general regeneration. Usage is implied rather than prescribed.

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 the safety profile (readOnlyHint=false, destructiveHint=false); the description adds substantial behavior beyond them: text/action are auto-drafted when content is omitted, dry_run previews the draft including prior text and reviewed requirements, alignment failures still save the story and surface via alignment_failure, and 409 fires on unanswered/already-converted questions.

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 core purpose and outcome branching, and every sentence carries actionable information. It is dense and somewhat run-on across five sentences, but there is little wasted text.

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

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

An output schema exists so return values needn't be re-explained, and the description still covers the mutation semantics, dry-run preview flow, alignment failure handling, and error condition. 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: how action interacts with content and revises_story_id (including the project-scoped vs story-scoped rule), that passing action without content drafts for that action, and that action/revises_story_id should be passed back from a dry run.

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: 'Write an answered open question's decision into the backlog,' then explains the two concrete outcomes (revise an existing story or create a new one). This clearly distinguishes it from siblings like stories_create and open_questions_answer without opening any schema.

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

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

Explicitly routes the agent: a story-scoped question 'usually revises that story,' a project-scoped question revises the settled story via revises_story_id, and 'otherwise... it becomes a new story.' It also states when to omit content (drafting), when to pass dry_run, and what the 409 failure conditions are.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds semantic context about what open questions represent, but says nothing about the lifecycle nuance (the schema notes 'open' questions may be replaced on regeneration), which would be the valuable extra detail.

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: the action and the conceptual definition come first, then the filtering options. Nothing is wasted and the most decision-relevant information is front-loaded.

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 an output schema present, return values need not be described, and annotations cover safety and world scope. The definition covers the essentials for a filtered read-list tool; only the enum-lifecycle nuance from the schema is unstated in prose.

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

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

Schema description coverage is 100% and the schema itself thoroughly documents status semantics and both UUID filters. The description only repeats the status values already listed in the schema, adding no syntax or behavioral detail beyond it — the baseline 3 for full schema coverage.

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: 'List the project's open elicitation questions,' and further defines what those questions are ('the points the spec leaves unresolved'). That is enough to separate it from siblings like open_questions_answer or open_questions_convert_to_story, though no sibling is named explicitly.

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

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

It states a clear use condition ('read them before assuming intent') and tells the agent what filters are available. It does not explicitly contrast with the alternative answer/convert tools, which is the only missing piece.

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 destructiveHint=false and openWorldHint=true, so the description's added value is elsewhere: it discloses that the call is proposal-only, that accepted links get merged with existing relationships rather than replacing them, and that execution 'may take several minutes' with progress notifications. That merge-vs-replace detail is exactly the kind of mutation semantics an agent cannot infer from the schema. It does not discuss authorization needs or what happens to the proposal if never accepted.

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?

Six short sentences, front-loaded with purpose and with no filler; the runtime note and the save-workflow note each carry distinct information. It is slightly more granular than necessary for a 10% weight dimension, but nothing is redundant.

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 annotations cover the safety profile; the description still covers propose-only behavior, selection defaults, merge semantics, and latency. The one remaining gap is the purpose of extra_requirement_attributes, which is undocumented in both the schema and the description.

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 baseline is 3, and the description adds genuine semantics: omitting chosen_reqs_ids/chosen_story_ids means 'use all requirements and stories,' which defines a default the schema does not state. It remains silent on user_message and extra_requirement_attributes, so it improves on the baseline without fully covering all five parameters.

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 opening sentence gives a specific verb and resource: 'Propose story-requirement links.' Combined with the follow-up that it returns a proposal without applying changes, an agent can distinguish this from the write-oriented siblings (requirements_update, stories_update) and from projects_align_stakeholders_to_stories. It stops short of naming an alternative align tool 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?

It states the default behavior ('Omit selections to use all requirements and stories') and the intended workflow ('Review it with the user, then save accepted changes using the existing CRUD tools'), which routes the agent to the right sibling tools for persistence. There is no explicit when-not-to-use guidance or statement of prerequisites (e.g., required project state), so it falls short of the full when/when-not/alternatives bar.

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?

Adds substantial context beyond the annotations: it does not apply changes (proposal only), it merges accepted links with existing relationships on save, it may run for several minutes, and progress notifications report elapsed time when supported. The 'without applying changes' statement sits in mild tension with readOnlyHint=false, but the description is clarifying rather than contradicting, and the latency/merge disclosures are exactly the kind of behavior annotations cannot 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?

Six short sentences with no filler, and the proposal-first constraint is front-loaded. It is slightly longer than strictly necessary but every sentence conveys distinct behavior for this workflow tool.

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 long-running AI proposal tool with an output schema, the description supplies the missing pieces an agent needs: default selection behavior, non-application of changes, merge semantics on save, and the handoff to CRUD tools. Nothing needed to invoke or follow up correctly is absent.

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 baseline is 3, but the description adds real semantics the schema does not: omitting chosen_story_ids/chosen_stakeholder_ids falls back to all stakeholders and stories. It adds nothing for project_id or user_message, which the schema already documents.

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 ('Propose stakeholder-story links') and clearly frames the output as a proposal rather than an applied mutation, which separates it from CRUD-style siblings. It does not name the nearest analogue, projects_align_requirements_to_stories or projects_align_to_story, so the sibling differentiation relies on the agent inferring from the 'stakeholder' vs 'requirement' wording.

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 operational guidance: omit selections to default to all stakeholders/stories, review the proposal with the user, then persist accepted links via existing CRUD tools. It says when to use and where the follow-up write happens, though it never states when not to use this in favor of the sibling align 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?

Adds meaningful behavior beyond the annotations: it returns a proposal without applying changes, merges accepted links with existing relationships on save, and may run for minutes with progress notifications. It also implicitly clarifies the tension with readOnlyHint=false by stating that no suggested changes are applied. This is rich disclosure, though the persistence semantics of the 'proposal' itself remain slightly unclear.

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 sentences, purpose front-loaded, each carrying distinct information (proposal semantics, merge behavior, next step, latency). The progress-notification clause is marginally extraneous but overall it is tight and well ordered.

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 rich output schema present, the description needn't explain return values, and the annotations cover the safety profile. It fills the remaining gaps by describing the async/long-running nature, the non-application guarantee, and the follow-up save path. Complete enough for an agent to call and act on it correctly.

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

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

Schema description coverage is 100%, so all three parameters (story_id, project_id, user_message) are already documented in the schema. The description adds the notion of 'including a new stakeholder if needed' but no parameter-level 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?

States a specific verb and resource: 'Propose stakeholders for an existing story identified by UUID.' This clearly distinguishes it from the alignment siblings (requirements-to-stories, stakeholders-to-stories) by naming the input (a story UUID) and the output (stakeholder proposals). It stops short of explicitly naming which sibling to prefer, so it is clear but not fully 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?

Gives explicit workflow guidance: 'Review it with the user, then save accepted changes using the existing CRUD tools,' which tells the agent what this tool does NOT do and where to go next. It lacks an explicit 'when-not' or named alternative tool for edge cases, but the usage context is clear.

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

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

Adds rich behavioral context beyond the annotations: it returns a proposal without applying it, re-running only proposes again and replaces saved items for the same targets, it applies nothing, and it may take several minutes with progress notifications. The write behavior (saving suggestions) is consistent with readOnlyHint=false and 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?

Front-loads the purpose before workflow routing, and nearly every sentence carries actionable information. It is somewhat long and dense, but the detail is justified by the multi-step workflow rather than padding.

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

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

For a complex, multi-step, write-related analysis tool with an output schema, it covers the proposal-vs-apply distinction, downstream routing, fallback ordering, re-run semantics, and latency. An agent has everything needed to call it and act on the result 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 parameters are already documented. The description restates 'by UUID' for the target requirements but adds no syntax or format detail beyond the schema, warranting the baseline 3.

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 verb (analyze), resource (selected requirements by UUID), and outcome (propose revisions or removals). It clearly distinguishes itself from CRUD siblings and from suggestions_accept/reject by framing itself as the proposal-generating step.

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: accepted items go to suggestions_accept, declined to suggestions_reject, and recreating with CRUD tools is forbidden. It also sequences the fallback (use suggestions_list, and only if absent, create via CRUD), covering when-not and alternatives thoroughly.

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 give readOnlyHint=false/openWorldHint=true/destructiveHint=false; the description adds three traits beyond that: the call is proposal-only and does not mutate project data, it may take several minutes, and it emits progress notifications with elapsed time when supported. The latency and non-mutation disclosure are exactly what an agent needs before scheduling a long, side-effect-free generation call.

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 load-bearing: action and output shape first, workflow second, operational caveat last. No filler and no repetition of schema or annotation content.

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 covers the essential arc (propose → review → persist). The only gap is that 'the existing CRUD tools' is left unnamed, leaving the agent to guess whether follow-up goes through suggestions_accept or stories_create.

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 already 75% (project_id, n_stories_to_generate, user_message all carry descriptions), so the schema is doing the heavy lifting. The description adds only a rationale for rejected_stories ('optionally supply previously rejected suggestions') and says nothing about user_message or the generation count, so it modestly exceeds but does not clear the baseline.

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

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

The description opens with a concrete verb+resource ('Suggest missing features and clarifying stakeholder questions') and immediately clarifies the output shape ('Returns a proposal without applying the suggested changes'). It does not name or contrast against the closest siblings (projects_make_stories_from_description, projects_align_requirements_to_stories, suggestions_list), so an agent still has to reason about which generation tool to pick.

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 a clear human-in-the-loop workflow: review the proposal with the user, then persist accepted changes via existing CRUD tools. That is real usage context (no auto-apply), but there are no explicit when-not conditions or named alternatives for overlapping generation/alignment 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?

Annotations mark readOnlyHint=false and destructiveHint=false, so the description's key addition is that it returns a proposal without applying suggested changes, resolving the ambiguity of a non-readOnly hint. It also discloses latency (may take several minutes) and progress notifications, though it says nothing about auth needs or rate limits.

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

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

Four short sentences with the purpose front-loaded and no filler. The save-workflow and latency notes are each worth their space, though the middle two sentences could be tightened into one.

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?

Output schema exists, so return values need not be restated, and annotations carry the safety profile. The description covers the propose-then-commit workflow and runtime cost, leaving only minor gaps such as what the proposal contains.

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 project_id and user_message are already documented in the schema. The only parameter-like names in the description (assessment_score, assessment_details) belong to projects_patch, not this tool, so the description adds no parameter meaning of its own.

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 object: assess project description and story completeness. It is clearly distinguishable from CRUD siblings, though it doesn't explicitly contrast itself with the similarly-aimed projects_analyze or projects_check_description, so the boundary is left for the agent to infer.

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 concrete workflow: this tool only proposes, then the agent must review with the user and persist accepted changes via projects_patch (with assessment_score/assessment_details) or the existing CRUD tools. It names the follow-up tool explicitly, but offers no when-not-to-use guidance versus the other analysis 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?

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description goes well beyond by disclosing that it saves but does not apply a proposal, that saved_suggestions/review_url are produced, the double-application hazard, that re-running replaces prior saved items rather than applying, and that execution may take minutes with progress notifications. This is rich, non-redundant behavioral 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?

Front-loaded with the purpose, then the workflow, then the recovery path, with every sentence carrying distinct operational information. It is dense and multi-sentence, but nothing is filler; a slightly tighter grouping of the apply/decline rules would make it 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?

For a multi-step, stateful audit tool, the description covers the full lifecycle: propose, save, review (saved_suggestions/review_url), accept/decline, the CRUD double-apply trap, re-run behavior, and a fallback when saved_suggestions is absent. An output schema exists, so return values need no further explanation.

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

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

Schema description coverage is 100% and both parameters (project_id, user_message) are fully documented in the schema, so the baseline is 3. The description adds nothing about parameter formats or how project_id/user_message shape the audit beyond what the schema already states.

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 ('Audit the story backlog') plus the exact output ('propose story creations, updates, or deletions'), and distinguishes itself from siblings by naming suggestions_accept, suggestions_reject, suggestions_list and the CRUD story tools. An agent can tell this is a propose-only audit tool without opening any schema.

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

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

Explicit lifecycle routing: apply accepted items via suggestions_accept, decline via suggestions_reject, do NOT recreate accepted items with CRUD tools (with the reason: double application), and a fallback chain (suggestions_list, then CRUD only if absent). Both when-to-use and when-not-to-use are covered, including the re-run semantics.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description earns credit for disclosing latency ('may take several minutes') and progress-notification behavior. It does not state what the feedback contains or that the check is nondeterministic/LLM-backed, which openWorldHint implies but the text never confirms.

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 purpose, then the non-mutation guarantee, then the latency caveat. No wasted words, though 'Returns feedback' is slightly vague given an 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?

With an output schema present, return details need not be spelled out, and the description covers the two things an agent most needs: that this is a pass/fail gate rather than a mutation, and that it can run for minutes with progress notifications. It omits any criteria for what 'sufficiently detailed' means, which would help the agent interpret results.

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 title, llm_name, and description are already documented in the schema. The description adds only that the 'description' text is the thing being evaluated, and says nothing about why title/llm_name are supplied to a check operation, leaving the baseline 3 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 target ('Check whether description text is sufficiently detailed') and immediately scopes it against the sibling it could be confused with ('does not create a project'). An agent can separate it from projects_create and projects_make_description without opening schemas, though the description never names those siblings directly.

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 trigger point is explicit: run this 'before creating a project' as a validation gate. It also clarifies the negative case (it returns feedback, it does not create), but gives no guidance on what to do when the check fails or on alternatives for generating/fixing a weak 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, destructiveHint=false, and openWorldHint=false, so safety is partially covered by structured data. However, the description adds nothing beyond that: it does not say what a created project contains, whether extra fields are optional, or what defaults apply to chosen_llm.

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 zero waste, but it is under-specified rather than genuinely concise. There is nothing extraneous because there is almost nothing at all.

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?

Given a mutation tool with a nested required object, an output schema, and several sibling create/import variants, 'Create a new project' is too thin. The output schema excuses explaining return values, but nothing here orients the agent on the required 'title' vs optional fields or on mutation consequences.

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

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

Schema description coverage is 100% and the nested 'project' object documents title, chosen_llm, design_description, and extra_requirement_fields thoroughly, so the schema carries the burden. With only one top-level parameter, baseline 3 is appropriate; the description adds no extra parameter 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?

The description gives a clear verb+resource ('Create a new project'), which is better than a pure tautology, but it offers no differentiation from siblings such as projects_import, projects_update, or stories_create. An agent cannot tell from this line why it would pick projects_create over projects_import.

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 when-to-use guidance, no prerequisites, and no mention of alternatives like projects_import. The only implied usage is the self-evident 'you want a new project', with nothing about the chosen_llm/design_description context that distinguishes this call.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this is an irreversible-feeling mutation. The description adds nothing beyond that — no statement about permanence, cascading effects on requirements/stories/subsystems, or required permissions. Restating "delete" contributes no behavioral 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?

A single front-loaded sentence with zero filler. It is efficient, though its brevity shades into under-specification rather than economy — the sentence is short because nothing was explained, not because everything was squeezed in.

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. But for a destructive, presumably irreversible project deletion, the definition omits cascading impact, permission requirements, and any pointer to recovery tools — meaningful missing context for an agent deciding whether to call it.

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

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

Schema description coverage is 100% and there is only one parameter (project_id, a UUID), so the schema fully documents the input. The description adds no format or sourcing detail, which is the expected baseline 3 when the schema does all the work.

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?

"Delete a project" states a specific verb and resource, so the agent immediately knows this removes a project rather than reading or updating one. It does not, however, contrast itself with adjacent siblings like projects_undo, projects_patch, or restore_project_snapshot, which are the tools most likely to be confused with a delete.

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 guidance about when deletion is appropriate, whether it can be undone, or that projects_undo / restore_project_snapshot exist as alternatives. For a destructive operation in a toolset full of sibling project mutations, this absence is a real gap.

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 give the coarse safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds substantive context the annotations cannot: the tool does not apply changes, requires user review, may run for several minutes, and emits progress notifications with elapsed time. It never states whether the proposal is persisted, which leaves a small 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?

Five compact sentences with the core behavior front-loaded. The mid-stream instruction sentence ('Create accepted new subsystems before applying their links') blurs the boundary between what this tool does and what the caller should do next, which slightly muddies an otherwise tight structure.

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 an output schema present, return-value detail is unnecessary, and the description still covers side-effect profile, latency, progress reporting, and the apply-vs-propose workflow. For a 4-parameter, annotated, output-described tool, nothing an agent needs in order 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 75%, so most parameters are self-documenting and the baseline is 3. The description indirectly references 'optional interface contracts' (mapping to generate_interface_contracts) but adds no meaning for granularity or user_message beyond what the schema already states.

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 first sentence gives a specific verb and resource ('Propose subsystem additions, changes, deletions, requirement assignments, and optional interface contracts') and the fourth sentence clarifies the output is a non-applied proposal. This distinguishes it from CRUD siblings like subsystems_create/subsystems_update, though the word 'Propose' is slightly softer than the tool name 'detect'.

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 prescribes the follow-up workflow clearly: review the proposal with the user, then apply accepted changes 'using the existing CRUD tools', and create new subsystems before linking them. It gives no explicit when-not-to-use or a named alternative detection tool, but the boundary against the apply-tools is well drawn.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety and repeatability are covered. The description adds the default-value behavior and the conceptual output shape, but says nothing beyond the annotations about the return payload detail (an output schema exists anyway) or any constraints. Adequate but modest added value.

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 tightly packed sentence front-loads the operation, then the operand options and default, then the output buckets and the motivating use case. Every clause carries information; nothing is padded or redundant.

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

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

With annotations covering the safety profile and a full output schema covering the buckets' structure, the description supplies everything needed to call it: required operands, the 'current' default, and the diff semantics. Minor gaps remain around prerequisites (must snapshots already exist?) and any ordering/limit behavior.

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

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

Schema description coverage is 100% and all three parameters (base, compare, project_id) are fully documented in the schema, including the 'current' sentinel and UUID formats. The description merely restates base/compare semantics, adding essentially no meaning beyond the structured fields — 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 ('Diff') and resource ('a project') plus the two operands (base snapshot vs. compare state), and enumerates the resulting buckets (ADDED/REMOVED/MODIFIED/UNCHANGED across stories, requirements, interface contracts). No sibling tool overlaps this snapshot-comparison function, so the agent can select it unambiguously.

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 a clear use context ('the basis for the implement only what changed loop') and documents the default of compare as 'current'. However, it names no alternative tool and offers no when-not guidance (e.g., when to just call get_project_snapshot instead), so routing 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 already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: matching is case-insensitive substring, results are natural-sorted, and each match carries a snippet plus the matched field.

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 with zero waste; the matching semantics and scope are front-loaded, and the return shape follows immediately. Nothing is padded or redundant.

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 search tool with a full output schema and 100% parameter coverage, the description is complete enough to select and invoke the tool correctly without explaining return values. It lacks only explicit alternative-routing 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?

Schema description coverage is 100%, so the schema already documents project_id, query, kinds, and limit in detail. The description's note on case-insensitivity and natural sort adds only marginal meaning over 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 (substring search) and resource (a project's stories, requirements, stakeholders, subsystems, interface contracts), enumerating the searchable entity kinds. This implicitly distinguishes it from the many single-kind list tools in the sibling set, which return full entities rather than matches.

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

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

Usage is implied by the description (cross-entity substring search) and the schema notes you can restrict kinds or omit to search all. However, there is no explicit when-to-use guidance versus alternatives such as stories_list, requirements_list, or stakeholders_list when looking up entities.

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 read-only and idempotent behavior, but the description adds real context: chat is opt-in, version 4 emits typed file-local links, and pending actions are stripped from the export. These are non-obvious transformation traits an agent cannot derive from annotations or 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?

Three front-loaded sentences with no filler, leading with the core purpose and the round-trip relationship. The version-4 internals are slightly dense but every clause conveys actionable 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 an output schema present, return-value detail is unnecessary, and annotations cover the safety profile. The description complements these by explaining the chat opt-in default and format consequences, leaving little an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters and the enum. The description largely restates the format behavior ("yaml returns the same export as a YAML document ... imports the same way once parsed") rather than adding syntax or semantics 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+resource ("Export a project") and identifies the counterpart tool it feeds ("the portable format projects_import reads"). It does not distinguish itself from the sibling exporters projects_export_openspec and projects_export_speckit, which an agent might otherwise pick, but the core purpose 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?

Provides a use case for the yaml format ("for committing to a repository") and notes round-trip compatibility with projects_import, implying when to reach for it. However, it never states when to choose this over the export_openspec/export_speckit alternatives or the plain JSON default, 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 already declare readOnlyHint/idempotent/openWorld=false, and the description usefully clarifies that the tool only returns path+content and the caller performs the write, which resolves any 'write out' ambiguity. 'Uses no AI and no credits' is a real cost trait not present in annotations, but no other behavioral detail (sizing, limits) is added.

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 output format and no filler. The return-value detail is arguably redundant given the output schema, but it is brief.

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

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

For a single-parameter, read-only export with an output schema, the description covers format, return shape, and cost. Nothing an agent needs in order 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 description coverage is 100% and the single project_id parameter is fully documented there; the description adds no meaning beyond what the schema already 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?

Specific verb ('write the project out') plus resource ('as OpenSpec files') and even the exact output layout (one spec.md per subsystem plus system-level). The OpenSpec format name implicitly separates it from projects_export_speckit, though no sibling is named explicitly.

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

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

The phrase 'write them into the repository to put the current spec back' implies the use case (persisting a snapshot of the current spec), but there is no explicit when-to-use/when-not guidance and no pointer to projects_export_speckit or projects_import_openspec as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing that the operation uses no AI and consumes no credits, and that it returns both path and content. It could still clarify that the tool itself does not persist anything to the repository (the caller does), which would remove residual ambiguity around 'Write the project out'.

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 concrete output path, and no filler. The phrase 'Write the project out' is slightly ambiguous against the read-only nature of the tool, costing a bit of precision.

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 an output schema present, return-value explanation is not required, yet the description still summarizes the return (path and content). Combined with annotations and a single fully documented parameter, the definition is nearly complete; only the tool-vs-caller write responsibility could be stated more explicitly.

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 with 100% schema description coverage, so the schema fully documents project_id. The description adds no extra meaning about the identifier or its scope, which is the expected baseline 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?

The description names a specific action and artifact: it writes the project out as one GitHub Spec Kit feature at a concrete path (specs/<NNN>-current-system/spec.md). It implicitly separates itself from siblings like projects_export_openspec and projects_import_speckit by naming the Spec Kit format and direction of flow.

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 the intended downstream consumer explicitly ('write it into the repository so /speckit-specify reads it'), which tells the agent exactly when this output is useful. It does not, however, compare against projects_export or projects_export_openspec, so the choice among export variants is left 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 only safety hints (readOnly=false, destructive=false, openWorld=true). The description adds substantial behavioral detail beyond them: it uses AI, spends credits, incrementally saves each folded feature, and encodes the folding rules (revise vs. copy, requirement-to-story linking, exclusion of engineering-only features, replacements becoming open questions).

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 trigger condition is front-loaded and the three sentences are dense but purposeful, with no filler. Some grammatical density makes it slightly harder to scan, but every clause carries semantics.

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 an AI-driven, credit-spending, resumable batch operation, it covers prerequisite, incremental persistence, side effects, and processing rules. An output schema exists, so return values need not be explained; nothing critical for correct 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 project_id and max_features are already documented in the schema. The description does not elaborate on parameter formats or defaults, so the baseline 3 applies since 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 and resource: 'fold the imported Spec Kit features into one backlog, oldest first.' It names the prerequisite sibling (projects_import_speckit) and describes the transformation outcome, so an agent can distinguish it from import/update siblings at a glance.

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 clear sequencing context ('After projects_import_speckit') and rerun guidance ('run again to resume'), telling the agent when the tool is applicable. It does not explicitly name when-not or an alternative for folding, but the trigger condition 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?

Goes well beyond the annotations, which only state readOnlyHint=false, openWorldHint=true, destructiveHint=false. It discloses that the tool saves proposals without applying them, that re-running replaces prior saved work for the same targets, the double-apply risk, and multi-minute latency with progress notifications.

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 core action and the non-applying scope before branching into routing. Dense but nearly every sentence carries necessary operational guidance; minor length inflation from the fallback sequence.

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 an async, side-effectful generation tool with an output schema and annotations, the description supplies the missing lifecycle context: proposal persistence, idempotency/replacement behavior, review URL, and latency. Nothing an agent needs to call it correctly is absent.

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 every parameter including creative_mode and max_attempts is already documented. The description adds no extra syntax or format guidance for the parameters, 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: generate requirement suggestions and revisions, preserving locked requirements. The proposal-without-applying scope plus the named sibling tools (suggestions_accept, suggestions_reject, suggestions_list, CRUD tools) make the function unmistakable against its many 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?

Explicit when-to-use and when-not-to-use: apply accepted items via suggestions_accept, decline via suggestions_reject, never recreate accepted items with CRUD tools, and fall back to suggestions_list only when saved_suggestions is absent. Routing and exclusions are 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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety and repeatability profile is fully covered by structured data. The description adds nothing beyond that profile — no behavior on a missing/unknown id, no indication of what the caller state must be to read it.

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 zero filler; every word earns its place. It is minimal rather than padded, though the extreme brevity borders on under-specification for the surrounding toolset.

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 one required parameter is fully documented in the schema. Annotations handle the safety profile, leaving only edge-case behavior (unknown id, permission requirements) unaddressed — a minor gap for a simple 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 100% and the sole parameter's UUID format is documented in the schema, so the baseline of 3 applies. The description's 'by id' merely restates the parameter without adding format, sourcing, or constraint detail.

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

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

The description states a specific verb ('Get') and resource ('a project') and pins the lookup key ('by id'), so the agent knows exactly what the call fetches. It never differentiates from nearby siblings such as projects_list, projects_overview, or projects_get_assessment, 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?

There is no when-to-use guidance at all: nothing tells the agent to prefer this over projects_list when it already has an id, or over projects_overview when it wants a summarized view. The single sentence only describes the operation, 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds essentially nothing beyond 'get details' – no note on what an assessment contains or what happens when none exists.

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

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

One short, front-loaded sentence with zero filler. Appropriately sized, though it is arguably too terse to be informative.

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 cover safety. However, for a tool embedded among dozens of near-identical project siblings, the description does not supply enough to make selection unambiguous.

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 project_id parameter is fully documented as a UUID. The description adds no parameter meaning 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 clear verb (get) and resource (assessment) scoped to a project, but is thin on specificity. It does not distinguish itself from sibling projects_get, projects_assess, or projects_overview, so an agent cannot easily tell which 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?

No guidance on when to use this versus the many similar siblings (projects_get, projects_assess, projects_overview). No exclusions or prerequisites are 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, openWorldHint=false and idempotentHint=true, so the safe-read profile is covered. The description adds essentially nothing behavioral beyond that – no pagination, ordering, or volume disclosure, which matters for a history-listing tool. With annotations carrying the safety burden, this is a modest 3.

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 lean sentence with no filler and the subject front-loaded. It is not padded, though it is so terse it sacrifices useful context for brevity.

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 explained, but for a history-retrieval tool the description omits ordering, time scope, pagination, and what a 'message' even is. Against a very crowded sibling namespace, this is too thin to guide 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 coverage is 100% and the single project_id param is fully documented in the schema, so baseline 3 applies. The description adds no format or constraint detail beyond what the schema already provides.

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

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

The description states a specific verb ('Get') and resource ('message history') scoped to a project, which is clearer than the sibling 'projects_get'. However, among dozens of project-scoped siblings it doesn't differentiate itself beyond name, and 'message history' scope (what messages, from where) is left unstated.

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 reference to alternatives. Given the crowded sibling set (projects_get, projects_overview, projects_list), an agent gets no routing help about when message history is the right call versus other project reads.

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 a non-readonly, non-destructive mutation, and the description adds real behavioral detail beyond that: pending actions are discarded, version-4 chat links rebind to fresh UUIDs, and legacy/unresolved links stay unbound. It does not disclose overwrite/duplicate-name behavior or id-remapping consequences for ordinary documents.

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 compact sentences with no filler and the core purpose front-loaded, followed by version-compatibility specifics. Each sentence carries information, though the third sentence overlaps somewhat with the chat-link clause of the second.

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 mutation/safety profile, so the description need not explain return values. Coverage of version compatibility, chat-link rebinding, and discarded pending actions makes it largely sufficient, with only conflict/overwrite behavior at import time left unstated.

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 single `data` parameter has no top-level schema description (0% coverage), so the description must carry it, and it only says the payload comes from the projects_export portable format. The nested schema does document field semantics richly, but the description adds little about the top-level document shape or required fields.

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+resource ('Import a project') and anchors it to a named counterpart format written by projects_export, which an agent can map directly. It distinguishes the tool from the format-specific siblings only implicitly (portable projects_export format vs. the openspec/speckit importers), so sibling differentiation is not fully explicit.

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

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

Usage is implied rather than stated: 'the portable format projects_export writes' tells the agent this is the counterpart to export, but there is no when-to-use/when-not-to-use guidance and no routing toward projects_import_openspec or projects_import_speckit for other formats.

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 cover readOnly/destructive/openWorld flags; the description adds genuinely useful behavior the agent cannot get elsewhere: no AI, no credits consumed, and a documented gap (no stakeholders or stories generated). It does not describe failure modes (e.g., repo without an openspec/ folder).

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 action and source, then the mapping semantics, then the constraints. No redundant restatement of the name or 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 not be explained. The description covers what the tool creates and explicitly what it omits; the only minor gap is error/precondition behavior when the target repo lacks an openspec/ folder.

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

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

Schema description coverage is 100% and the single url parameter is fully documented in the schema, including accepted URL formats. The description adds no parameter-level detail beyond what the schema already says, 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?

Specific verb (Create) plus resource (project) and the precise source kind (public GitHub repo using OpenSpec). It further states the mapping model (spec domain → subsystem, requirement → requirement, scenarios → acceptance criteria), which cleanly separates it from projects_import_speckit and projects_import.

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 scopes usage implicitly via 'Uses no AI and no credits; stakeholders and stories are not generated', telling the agent when not to pick it (if stories/stakeholders are needed), but it never names the alternative sibling tools (projects_import_speckit, projects_import) explicitly.

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 write/non-destructive/non-open-world, and the description adds genuinely non-obvious behavior: it uses no AI and no credits, and it discloses exactly how content maps (stories and requirements verbatim, clarifications as answered questions, statuses from tasks.md). It does not state permissions or whether an existing project is overwritten.

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, verb-first and front-loaded, with dense but relevant detail about the mapping and the separate folding step. 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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the format constraint, the transformation behavior, the no-AI/no-credit trait, and the follow-up step, leaving nothing an agent needs to invoke 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 url parameter is fully documented in the schema, including accepted forms (URL, owner/repo, /tree/ link). The description only restates the 'public GitHub repository' constraint, adding little 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 (Create) and resource (a project) with the precise input format (public GitHub repo using Spec Kit specs/<feature>/spec.md). This clearly separates it from the OpenSpec and plain-import siblings, though it does not name those alternatives 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?

It implies the correct context (import now, fold features into one backlog separately) and names the follow-up step, but never states when to choose this over projects_import or projects_import_openspec, nor does it give prerequisites beyond 'public' repo.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds the 'current user' scoping constraint, which is useful, but says nothing about pagination defaults, ordering, or result volume. With annotations carrying the safety burden and an output schema present, 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 short sentence with no redundancy or filler. It is front-loaded and readable, though it is arguably under-specified rather than perfectly calibrated.

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 output schema covers return values and the annotations cover safety and idempotency, so the largest burdens are lifted. However, given a wide sibling set with several overlapping list/search tools, the description is too thin to route an agent confidently and omits pagination behavior.

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

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

Schema description coverage is 100% and both parameters (skip, limit) are documented directly in the schema. The description adds no syntax, default, or maximum-value 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 (List) and resource (projects) with a scoping qualifier ('for the current user'). It does not distinguish itself from sibling list-like tools such as project_search, projects_overview, or projects_get, so an agent cannot tell from the description alone when this is the right call versus those.

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 when-to-use guidance, no exclusions, and no mention of alternatives among a very crowded sibling set (project_search, projects_overview, projects_get_many patterns). The agent must infer context from the name 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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds only the sort order ('most recent first'), which is mild extra context, but says nothing about pagination defaults or result shape.

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

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

Two short sentences, zero padding; the core purpose and ordering lead, and the downstream hint follows. 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 an output schema present, return values need no explanation, and pagination is covered by the schema. The description supplies scope, ordering and the follow-on tool, leaving only sibling disambiguation as 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% (skip, limit, project_id all documented in the schema), so the baseline is 3. The description restates only the project scoping and adds no format or default details beyond what the schema already carries.

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 saved snapshots for a project') plus the ordering guarantee (most recent first), which an agent cannot infer from the name alone. It does not explicitly distinguish itself from the sibling get_project_snapshot, 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?

It gives one forward-looking usage hint ('Use a snapshot id as the base for projects_diff'), which is genuine guidance. However, it never says when to pick this over get_project_snapshot, nor any prerequisite like needing an existing project, so guidance remains 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?

Adds real behavioral context beyond the annotations: the result is a non-applied proposal, saving happens through a separate tool, and the call can take several minutes with progress notifications. There is mild tension with readOnlyHint=false (the tool may persist generated content), but the description never claims pure read-only behavior, so it is not a contradiction.

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 core action, then the persistence guidance, then the latency caveat. Five short sentences, all earning their place, though the saving workflow could be tightened slightly.

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 description covers the action, the non-applied nature of the result, the save path, and latency. Complete enough to invoke correctly, with only the sibling-routing guidance 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; every parameter including stakeholder, user_message, and extra_requirement_attributes is already documented in the schema. The description names the design_description field used for saving, but adds no syntax or format detail beyond what the schema provides.

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 ('Draft a project description') and immediately clarifies the output is a proposal rather than an applied change, which separates it from siblings like projects_check_description (validates) and projects_make_stories_from_description (derives stories). An agent can identify what this produces 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?

Gives concrete usage flow: draft, review with the user, then persist accepted text via projects_patch with design_description. It names the save path and the review step, but never states when NOT to use it or how it differs from adjacent generators such as projects_specify_design or projects_generate.

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 say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond that: it discloses that no changes are applied (proposal-only), that changes must be committed separately, and that the call may take several minutes with progress notifications. Those are exactly the behavioral traits annotations cannot convey.

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

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

Three short sentences, front-loaded with what is produced, followed by the workflow constraint and the latency caveat. Every sentence carries distinct information with no repetition of the title or 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 not be described. Given the AI-generation workflow, the description supplies everything else an agent needs: the input basis, the proposal-not-commit semantics, the review step, the follow-up tools, and the long-running behavior.

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

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

Schema description coverage is 100%, so project_id, llm_name, and user_message are already documented individually, including the LLM enum example. The description references the project description as the source but adds no format, default, or interaction detail for any parameter, so baseline 3 applies.

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

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

States a specific verb ('Draft') and specific resources ('stakeholders and their stories') plus the input source ('from the project description'). This cleanly separates it from sibling generation/alignment tools such as projects_align_stakeholders_to_stories or projects_make_description without opening any schema.

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

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

Explicitly defines when and how to use it: it returns a proposal, the agent must review it with the user, and accepted changes are saved with the existing CRUD tools. This routes the agent to the correct follow-up siblings (stakeholders_create, stories_create) and states the non-application constraint.

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 readOnly/idempotent/non-open-world safety, so the bar is lower. The description adds genuinely useful context beyond them: "Uses no AI and no credits," which matters for cost-sensitive agent planning. The credits/AI-usage mention also signals the payload contains billing-relevant data.

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

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

Front-loaded with the payoff first; the long enumeration is dense but each item earns its place by describing the payload. The trailing "Read it first" and "Uses no AI and no credits" sentences are short and high-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?

An output schema exists, so return-value detail is not the description's burden, and annotations cover the safety profile. Combined with the usage cue and cost disclosure, the definition is essentially complete for a single-parameter aggregate reader.

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 project_id (UUID). The description adds no syntax or format detail beyond the schema, so the baseline of 3 for a fully-documented parameter set 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 precise aggregate read: counts of stakeholders, stories, requirements (by category and lifecycle status), subsystems, open questions, gaps, one suggested next step, and credits used. This composite nature clearly distinguishes it from siblings like projects_get, projects_assess, or projects_analyze. An agent can tell what it returns 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?

"Read it first when starting work on a project" gives explicit when-to-use guidance, which is valuable given the many sibling read tools. It does not, however, name a when-not condition or a specific alternative for narrower queries.

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 safety profile is covered. The description adds nothing beyond them: it does not disclose that this is a merge-style partial update, that omitted fields remain unchanged (that fact lives only in the schema description), or what side effects a patch may trigger. With annotations carrying the baseline, the description still contributes no extra behavioral 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?

While extremely short, this is under-specification rather than conciseness. For a tool that partially mutates a nested project structure, two words are not an appropriately sized explanation, and nothing is front-loaded because there is nothing to front-load.

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 takes a nested patch object with seven possible fields plus a UUID, has an output schema (so return values need not be described), and has no annotation-based behavioral detail. Given that complexity, the description is materially incomplete: it omits patch semantics, prerequisites, and any warning about destructive-ish overwrites of arrays such as messages.

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

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

Schema description coverage is 100%, and the nested patch object documents every field (title, messages, chosen_llm, assessment_score, etc.) plus the "omit fields to leave unchanged" semantics. Per the rubric this establishes a baseline of 3; the description adds no syntax, format, or constraint detail on top of 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?

"Patch a project" gives a specific verb (patch) and resource (project), so the basic operation is identifiable. However, it does nothing to distinguish this from siblings like projects_update or requirements_patch, and it never states what a "patch" means semantically here (partial merge vs. full replace). Minimum viable but not differentiating.

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 when-to-use guidance, no mention of when to prefer projects_update instead, and no preconditions such as required permissions or project state. The design decision of patch-vs-update is left entirely to the agent to infer from sibling names alone.

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

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

Annotations only give readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds the crucial behavioral facts those annotations cannot convey: the call is generative but non-committing (a proposal is returned), the agent must get user review before persisting, persistence happens via separate CRUD tools, and the call can run for minutes with progress notifications. Nothing here contradicts 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?

Four short sentences, no redundancy, and the core action is front-loaded before the workflow and performance caveats. Every sentence carries distinct information (what it does, what it returns, what to do next, how long it takes).

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 detail is unnecessary, and the description still supplies the two things an agent most needs beyond schema: that no changes are applied and how to commit accepted results. Combined with the latency note, an agent can plan the whole interaction 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 all five parameters (project_id, chosen_reqs_ids, max_attempts, user_message, extra_requirement_attributes) are already documented. The description only glosses 'by UUID' and 'parent links' and adds no syntax or semantics for max_attempts, user_message, or extra_requirement_attributes, 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 precise verb ('Propagate'), the source resource ('selected system requirements by UUID'), the target ('requirements for existing subsystems') and the mechanism ('with parent links'). This is instantly distinguishable from close siblings like projects_propagate_stories or projects_align_requirements_to_stories without opening any schema.

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

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

Explicitly tells the agent the tool does NOT apply anything ('Returns a proposal without applying the suggested changes'), prescribes the follow-up workflow ('Review it with the user, then save accepted changes using the existing CRUD tools'), and sets a latency expectation ('May take several minutes'). This is when/when-not/alternative routing in one compact block.

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=false, destructiveHint=false, and openWorldHint=true. The description adds substantial non-obvious behavior: it returns a proposal without applying anything, persists it for review with ids and a review_url, that re-running replaces the saved proposal for the same targets, the double-application pitfall, and that it may take several minutes with progress notifications. This goes well beyond what the annotations convey.

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

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

Purpose is front-loaded, and every subsequent sentence carries routing or behavioral payload rather than filler. It is dense and fairly long, but the length is justified by the multi-step accept/reject/fallback workflow it must convey; no sentence is redundant.

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 re-explained, and the description still names the key returned fields (saved_suggestions, review_url). Combined with the full workflow guidance and duration/notification disclosure, nothing an agent needs to call 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?

Schema description coverage is 83%, so the schema already documents project_id, chosen_story_ids, max_attempts, user_message, and extra_requirement_attributes. The description only implies 'stories by UUID' and 'optional subsystem requirements' (mapping loosely to propagate_to_subsystems), adding marginal meaning beyond the schema. 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 (propagate), the resource acted on (selected stories by UUID), and the destination (system requirements plus optional subsystem requirements with traceability links). This clearly distinguishes it from the similarly named sibling projects_propagate_requirements_to_subsystems, which propagates in the opposite direction.

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 through the whole workflow: apply accepted items via suggestions_accept, decline with suggestions_reject, do not recreate accepted items with CRUD tools, fall back to suggestions_list and only then CRUD tools if saved_suggestions is absent. It also states the consequence of re-running (re-proposes and replaces, applies nothing). This is exhaustive 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=false (a mutation) and destructiveHint=false, so the safety profile is covered. The description scopes the effect to 'the last undone change', adding some useful context, but says nothing about what happens when there is no undo history or whether the redo is itself reversible.

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 sentence, front-loaded with the verb and scoped to the specific target. Nothing extraneous.

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

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

For a single-parameter mutation tool with full schema coverage and an output schema (so return values need no explanation), the description is close to complete. It could mention the precondition of an existing undo state, but the core is 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?

With a single parameter at 100% schema coverage, the schema fully documents project_id as a Project UUID. The description adds no meaning beyond it, which is the expected baseline 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 (redo) and resource (last undone project change), which is immediately distinguishable from the sibling projects_undo. It does not explicitly name projects_undo as the inverse, but the phrasing leaves little ambiguity about the operation.

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 'last undone change' implies the usage context (this follows an undo), but the description never states when to use this versus projects_undo, nor any precondition such as an existing undo history. Usage 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds crucial behavioral context: it returns a proposal without applying changes, and may take several minutes with progress notifications. This is valuable information beyond what annotations provide. However, it doesn't detail what the proposal contains or error scenarios.

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 earning its place: what it does, how to use the result, and the performance characteristic. Front-loaded with the core purpose, then workflow guidance, then operational note. No waste.

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?

Complete for this tool's complexity. The output schema exists (so return values don't need explanation), annotations cover the safety profile, and the description adds the critical workflow context (proposal-only, review-then-save) and performance expectation. An agent has everything needed to invoke and handle this 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 all 3 parameters are documented in the schema. The description mentions linking to system requirements but doesn't add meaning beyond the schema's parameter documentation. Baseline 3 applies when schema does the heavy lifting.