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

The description reveals that the draft sends nothing, requires an author key (ek_mcpa_), returns specific problems for invalid plans, and is labelled machine-written in the dashboard. This adds significant context beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), which only declare basic safety flags.

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

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

The description is four sentences long, with each sentence adding unique value: purpose, prerequisite, safety workflow, auth and error handling. There is no redundant content or filler.

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

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

The description covers prerequisites, side effects, auth, and error handling, which is thorough for a single-parameter tool. However, since there is no output schema, it omits the success return value (e.g., a draft ID or confirmation), which is a minor but notable 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?

The only parameter 'plan' is described in the schema with a pointer to the journey-plan-schema resource, and the tool description reinforces this by telling the agent to read that resource for format and a worked example. This compensates for the schema's minimal 'additionalProperties' constraint.

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 'Create a DRAFT journey from a plan', using a specific verb and resource with clear scope. It distinguishes itself from sibling tools (list/describe/generate/mark/get) as the only creation tool.

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 instructs the agent to read the payghaam://journey-plan-schema resource first, establishing a clear prerequisite. It also explains the draft-review-activation workflow, providing context. It doesn't explicitly name alternative tools, but none of the siblings serve the same purpose, so the use case is unambiguous.

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

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

Annotations mark it read-only and closed-world, but the description adds useful behavioral context: it returns a plain-English, step-by-step breakdown and includes the state of each required event. This goes beyond the safety hint by describing the output's content and intended interpretation, without contradicting 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?

Two concise sentences convey purpose, output content, and a use case without filler. The key behavioral information is front-loaded, and every clause contributes meaning.

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

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

For a single-parameter, read-only tool in a well-defined domain, the description covers what it does, how the output is presented, and when to call it. It omits explicit return schema but the output is naturally described as a plain-English explanation, which is sufficient for this simple 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?

The input schema already documents journeyId as 'From list_journeys,' giving the agent sufficient sourcing information (100% schema coverage). The description does not elaborate on the parameter, but none is needed; it does not add semantics beyond naming a single journey, so it remains at the high-coverage baseline of 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?

The description clearly explains the tool's function: describing one journey's steps and the state of every event it needs. It distinguishes this from sibling tools by focusing on a single journey rather than listing journeys or events, while 'what one journey does' functions as a specific purpose statement.

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 explicitly states when to use the tool: 'Use this to understand what a missing event actually blocks before deciding where to track it.' However, it does not name alternatives or provide exclusions, so it stops short of full usage 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 indicate the tool is read-only, and the description adds determinism ('Regenerating produces an identical file') and explains the exactness of event matching. The instruction 'Write it into the repo' could cause slight ambiguity about whether the tool writes or the agent writes, but it does not contradict the readOnlyHint.

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

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

The description is concise with three sentences that front-load the main purpose. The middle sentence is an actionable usage instruction, and the third provides useful determinism context. The phrasing is slightly run-on but each sentence earns its place.

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

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

For a code generation tool without an output schema, the description adequately explains the output is a file and highlights determinism. However, it does not detail the output format or explicitly clarify that the tool generates content while the agent writes it, leaving a minor completeness 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 baseline is 3. The description only adds meaning to the platform parameter ('the language you ask for') and does not elaborate on the events or packageName parameters 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 clearly states the tool generates typed event constants for the project's events in a specified language. The verb 'generate' and resource 'constants file' are specific, and it distinguishes itself from sibling tools that list or mark events rather than generate code.

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

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

The description implies usage by instructing to write the file and use constants instead of string literals, and it notes idempotent regeneration. However, it does not explicitly mention when to use this tool over alternatives like list_expected_events or mark_events_declared, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true, which is not contradicted. The description adds some context by mentioning the 'instrumenting' check, but it does not disclose return format, side effects, or what happens if the key is unknown. With annotations covering safety, this is adequate but not rich.

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

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

The description is a single sentence with no wasted words, and it is front-loaded. However, phrasing as a question rather than a declarative statement slightly reduces clarity, but it remains appropriately concise for a zero-parameter 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?

With no output schema, the description should explain what the tool returns or how the output is structured. It only hints at the answer (project ownership and instrumentation status) without specifying the format or terminology, such as what 'instrumenting' means in practice. This leaves significant ambiguity for a tool that likely returns a summary object.

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

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

The tool has zero parameters, so the baseline is 4. The description need not add parameter-level detail, and it does not. The schema coverage is trivially 100% since there are no properties.

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

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

The description clearly identifies the resource (Payghaam project) and the specific information provided (which project a key belongs to, and whether instrumenting is needed). It distinguishes itself from sibling tools which focus on events and journeys, though it lacks a strong imperative verb, relying on the tool name for that.

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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent to infer when to invoke get_project_context.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to state safety. It adds useful domain context about what these events represent, but it does not disclose any additional behavior such as sorting, pagination, or output format. This is adequate for a simple list tool but not rich beyond 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?

The description is three short sentences, front-loaded with the core purpose, followed by a meaningful elaboration and a clear usage directive. Every sentence earns its place with no redundancy or fluff.

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

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

For a zero-parameter, read-only list tool with no output schema, the description is sufficient: it defines what is listed, why it matters, and how to start using it. It could explicitly mention that the tool returns a list, but the title and noun-phrase construction make that obvious. The 'Start here' guidance adds practical completeness.

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

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

The tool has zero parameters, and the input schema is empty. According to the rubric, a zero-parameter tool gets a baseline of 4 because there are no parameter semantics to clarify. The description does not need to add anything.

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

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

The description clearly identifies the tool's purpose: listing events that journeys wait on but which have never arrived. It distinguishes this from sibling tools like list_journeys by focusing specifically on missing events, making it the obvious first step for diagnosing stuck journeys.

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 'Start here' provides explicit usage guidance, indicating this tool is the entry point for investigating blocked journeys. It gives clear context (users stuck forever) but does not explicitly name alternatives or when not to use it, which would merit a 5.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the scope ('active journeys') and the output nature ('events each one depends on'), providing useful context. However, it does not discuss pagination, ordering, or potential size limits, so it adds moderate value beyond 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?

The description is a single, concise sentence that packs the core purpose and scope without any filler. Every word is meaningful, making it optimally concise and 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?

For a simple zero-parameter listing tool with readOnlyHint and no output schema, the description adequately conveys what the tool returns. It might be improved by noting the output format or whether inactive journeys are included, but the current text is sufficient for basic use.

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 zero parameters, the schema is trivially covered. The description's mention of 'active journey' and 'events each one depends on' clarifies what the output will contain, which is the essential semantic info. Baseline 4 for zero-parameter tools 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?

The description clearly states the tool's purpose: listing every active journey in the project and the events each depends on. This is specific and distinguishes it from sibling tools like list_expected_events (likely more focused on events) and describe_journey (likely for a single journey).

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?

Context implies use when a broad overview of active journeys and their dependencies is needed, but there is no explicit when-to-use or when-not-to-use guidance relative to siblings like list_expected_events or describe_journey. The description is informative but lacks exclusionary 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?

The description discloses that the tool updates the dashboard to reflect events as declared but not yet arrived, which is a behavioral detail beyond the annotations. It also clarifies the prerequisite of having written tracking calls. Annotations already cover idempotency and non-destructiveness.

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

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

The description is two sentences, with the primary instruction front-loaded. It avoids fluff and every sentence contributes to understanding when and how to use the 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 simple single-parameter tool with no output schema, the description covers the purpose, timing, and constraints. It doesn't elaborate on return values, but the annotations and context make this acceptable. The idempotency hint is present in annotations.

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 schema already documents the 'events' parameter with 100% coverage. The description adds the crucial constraint that only events with actual written tracking calls should be included, reinforcing the 'actually written' condition from the usage guidance.

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

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

The description clearly identifies the tool's function: reporting events as declared after writing tracking calls. It uses a specific verb ('tells the dashboard') and distinguishes this from planning-only, aligning with the tool name and title.

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

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

It explicitly states when to call ('once you have actually written the tracking calls') and when not to ('Do not call it for events you only planned to add'). This provides clear usage guidelines with an exclusion, though it doesn't name alternative sibling tools.

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