Genchi

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely important behavior beyond that: the actual connection cannot be performed here because Slack requires a browser-based permission grant, which prevents an agent from falsely reporting a completed connection.

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, followed by the product rationale, the browser constraint, and the trigger conditions. Every sentence carries weight, though the Slack check-in rationale is slightly expansive for a definition of this simplicity.

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 purpose, when to invoke, and the critical execution constraint, leaving nothing an agent needs in order to call this 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?

The tool takes zero parameters, so the baseline of 4 applies. The description does not invent or misdescribe any inputs, and its focus on status reporting is consistent with a parameterless call.

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: explaining how to connect a Slack workspace and reporting current connection status. The scope is unambiguous and instantly distinguishable from the initiative/blocker siblings, which operate on an entirely different domain.

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

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

Gives explicit trigger conditions: 'when someone asks how to set up Slack or why they are not receiving check-ins.' Strong forward guidance, though it names no when-not condition or alternative tool.

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

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive, closed-world), so the description needn't restate that. It adds genuinely useful creation-side behavior: the creator becomes Owner, the initiative starts on a weekly Friday check-in cadence, and no team members are added at creation time — they must be added later in the web app. That post-creation constraint is exactly the kind of context 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?

The actionable verb and the domain definition are front-loaded, and the closing sentence routes the usage condition. Four sentences is slightly more than strictly needed — the check-in cadence explanation could be tightened — but each sentence contributes either domain context or default-state behavior, so there is little 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?

With an output schema present, the description does not need to explain return values, and it covers the remaining gaps an agent would care about: ownership assignment, initial cadence, absence of team members at creation, and the explicit usage trigger. Nothing needed to call this three-parameter creation tool 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 each of the three parameters (name, goal, completion_date) carries rich schema-level documentation, so the schema does the heavy lifting. The description adds no parameter-level syntax or format detail beyond the schema, so the baseline of 3 is appropriate; its value lies in defaults, not argument semantics.

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 specific verb and resource ("Create a new initiative") and goes further by defining what an initiative is ("a named piece of work that a team casts a two-second check-in against each week"), so an agent understands the domain object, not just the operation. It is also clearly separable from siblings like genchi_list_initiatives or genchi_get_weekly_summary, which read rather than create.

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

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

It gives an explicit trigger condition: "Use this when someone explicitly asks to create or set up a new initiative," which also implicitly excludes read-side siblings. There is no explicit when-not guidance (e.g., what to do if the initiative already exists, or that member management cannot happen here), but the intended context is unambiguous.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: blockers are comments flagged as blocking and are attributed to the raiser, which distinguishes them from confidence check-ins. It doesn't mention volume, ordering, or whether multiple initiatives can be queried at once.

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 purpose and followed by definitional context and usage examples. 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?

A read-only tool with a full input schema, an output schema, and complete annotations; the description covers what it returns conceptually and when to call it. Adequate — the missing piece is only the boundary against the confidence-check sibling.

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

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

Schema coverage is 100% and the single parameter's description already explains partial, case-insensitive matching, so the description adds nothing about the parameter. It does scope the query to 'one initiative', but that is implied by the required singular parameter. Baseline 3 applies 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?

States a specific verb+resource ('get the blockers currently raised against one initiative') and defines what a blocker actually is, which is non-obvious domain vocabulary. It contrasts with confidence check-ins, though it doesn't name the sibling tool genchi_get_confidence 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?

Gives concrete triggering questions ('what is blocking the migration', 'why is confidence dropping'), which is clear usage context. It stops short of stating when NOT to use it — e.g. that the confidence-over-time question might be better served by genchi_get_confidence.

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/non-destructive, so safety is covered. The description adds real behavioral context beyond that: results are anonymous, individual votes are never attributed to a person, and it discloses the shape of the rendered chart and what aggregates are returned.

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, followed by the return summary, then the routing rule to the sibling. Slightly dense across five sentences, but each sentence (including the example queries) carries distinct information and none is 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?

Even though an output schema exists, the description adds the anonymity guarantee, the early-warning framing, and the sibling routing needed to call this correctly. Nothing an agent needs is missing for a single-parameter read tool.

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

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

Schema coverage is 100% and the single parameter's case-insensitive partial-match behavior is already documented in the schema. The description reinforces single-initiative scoping ('ONE initiative') but adds no syntax or format detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb+resource (get confidence signal and trend for ONE initiative) and explicitly contrasts with the sibling genchi_list_initiatives for the multi-initiative / beneath-initiative case. An agent can distinguish it 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?

Explicitly says when to use it (single-initiative questions, with concrete example queries like 'is anything slipping') and when not to (work beneath an initiative, or spanning several), naming the alternative tool to use instead.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful domain behavior: the summary compares confidence with last week, shows a trend, includes blockers from the past seven days, and is the same view the Owner receives each Friday. It does not add auth or rate-limit details, but those are not necessary for a read-only tool with an output schema.

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

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

The description is two sentences, front-loaded with what the tool returns and followed by concrete usage examples. Every clause adds useful information without redundancy.

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

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

Given the tool has one required parameter, full schema coverage, rich annotations, and an output schema, the description is complete enough for correct selection and invocation. It explains the summary contents and the intended use cases without needing to restate return values.

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 parameter's schema already documents that it accepts a full or partial initiative name with case-insensitive matching. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 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 ('Get') and resource ('weekly summary for one initiative in Genchi'), then enumerates the contents: confidence signal vs. last week, recent trend, and past-week blockers. This clearly distinguishes it from sibling tools like genchi_get_confidence and genchi_get_blockers because it is a composite weekly rollup, not a single-signal query.

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 clear use cases with example questions such as 'what changed this week' and 'give me the weekly update.' However, it does not explicitly state when to use this tool versus alternatives like genchi_get_confidence or genchi_get_blockers, so it lacks the exclusionary routing guidance that 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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the optional filter only changes the display (opens a tree on that initiative) while the full list is still returned, which is non-obvious and useful. It omits auth/visibility scoping details and pagination, keeping it short of a 5.

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

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

Front-loaded with purpose, then routing guidance and parameter guidance in a logical order. Slightly redundant: 'the full list is still returned' appears twice (once in prose, once restated), which costs a little efficiency but does not obscure the message.

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 explanation is unnecessary. For a single optional-parameter, read-only list tool the description covers purpose, routing, nesting behavior, and the filter's display effect — 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 coverage is 100% and the parameter's own description already covers case-insensitive partial matching and the tree display. The description reinforces the intent (use it when asked about work beneath an initiative) but adds little syntactic meaning 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 (initiatives visible to this person in Genchi) plus the payload (anonymous confidence signal per initiative). It also clarifies nesting semantics via the 'Part of' column, which separates it from write-oriented siblings like genchi_create_initiative.

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 trigger phrases ('what am I tracking', 'how are my projects doing') and names the exact condition for using the optional parameter ('what's happening under the platform programme', 'break down Infrastructure Modernisation'). An agent knows both when to call it and when to pass initiative_name.

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