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

With no annotations, the description carries the burden and does it well: it discloses sort order (timestamp descending), the default compact projection and that excerpts are trimmed rather than missing, the concrete rationale (a 60-row window measured 43.9k chars against the MCP result ceiling), and the 40-row cap. It omits auth/rate-limit context, but the response-shaping disclosure is unusually strong.

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 action, then structured into returns/default/escape-hatch guidance. The parenthetical about the 43.9k-char measurement is slightly over-detailed for a tool description, but it justifies the compact default and every sentence carries information.

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

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

An output schema exists, so the description need not explain return values, yet it covers the key operational risks (default projection semantics, cap, how to widen). For a 4-param read tool with zero annotations, what remains missing is chiefly the when-to-use routing against sibling tools.

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 meaning beyond the schema: it clarifies that compact means excerpted rather than missing fields, that fields="all" retrieves full records, and that the compact window caps at 40 rows so agent_id is the preferred narrowing lever rather than limit.

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 — querying Agent activity records for a team — and the second sentence adds the return shape (tool name, duration_ms, I/O summary). It does not, however, distinguish itself from plausible siblings like task_execution_trace or event_list, so an agent must infer which activity surface is the right one.

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 useful operational guidance — narrow with agent_id rather than widening limit, use fields="all" for full records — which is implied when-to-use advice. But it never says when to prefer this over sibling listing/telemetry tools, and there are no explicit 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?

No annotations are provided, so the description carries the full burden and does so: it discloses the projection contract (which fields are kept vs omitted), the retention guarantee ('Nothing is deleted: the count is always reported'), and the operational meaning of offline (terminated process, cannot be messaged or assigned work). This is exactly the kind of context an agent needs to interpret a truncated payload without assuming data loss.

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 core purpose, then layers projection and offline semantics in short paragraphs. Slightly dense with parenthetical asides, but every sentence carries behavioral information rather than filler.

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

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

For a six-parameter, output-schema-backed list tool with an unusual split-response design, the description supplies the projection, pagination-adjacent, and offline-handling context needed to call it correctly. An output schema exists so return shape needn't be restated, and the description wisely focuses on semantics instead.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, setting the baseline at 3. The description reinforces intent (compact is a trimmed view, 'NOT missing fields') and explains that offline rows fold into a count plus digest, but adds little parameter syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Lift a team's members') with a scope qualifier ('live roster first, offline history on request'). It is clearly distinguishable from 'team_list' (which lists teams) and 'agent_update_status' (which mutates), though it never names a sibling to route the agent 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 strong guidance on which parameters to use (default compact vs fields="all", include_offline for full history) but no guidance on when to choose this tool over alternatives like team_status, agent_activity_query, or team_list. Usage is implied by the payload semantics rather than stated as a selection rule.

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

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

With no annotations provided, the description carries the full behavioral burden and largely meets it. It discloses that this is a read/recommend operation (no mutation), that the default output is a COMPACT trimmed projection (not missing fields), and that the resume_hint is a ready-to-run call requiring summary. The 'does not mutate — Leader decides' framing is explicit. Minor gap: it doesn't explicitly state what happens on empty/no-match results or whether candidate data is sourced from storage vs live state.

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 dense paragraph followed by a focused second paragraph on availability tiers and addressing, and a closing on the default compact response. Every sentence earns its place — purpose, decision actions, availability framework, addressing semantics, fallback, and output projection. No filler, no repetition of schema content that isn't enriched.

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

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

For a tool with 6 params, an output schema, and no annotations, this description is thorough. It explains the decision model (three actions), availability tiers, addressing semantics, name-vs-id fallback, and output projection behavior. The output schema exists so return-value details needn't be in the description. It covers the behavioral and operational context an agent needs to correctly invoke and 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 coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining the 'Address candidates by NAME' vs agentId fallback semantics, what resume_hint contains (ready-to-run call), and the compact vs all projection meaning (trimmed, NOT missing fields). The 'fields' behavior is enriched beyond its schema line, and the project_id/session_id scoping is clarified (cross-session inference). This lifts it above 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 clearly states the tool's purpose: recommend whether to reuse an existing sub-agent for follow-up work, ranking candidates by domain match and returning one of three actions. It is specific about the verb+resource (recommend reuse) and the decision framework (reuse/slim_then_reuse/spawn_new). Among siblings like agent_list, agent_template_recommend, and fleet_dispatch, this stands out as the reuse-decision tool, not just an enumeration or dispatch mechanism.

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 it ('follow-up work: bug re-fix, deeper research, same-domain iteration') for resuming a prior sub-agent to preserve accumulated context. It clarifies the tool only recommends and the Leader decides. The availability tiers and the addressing guidance (by NAME vs agentId fallback) provide strong operational context. While it doesn't name specific sibling alternatives, the situational trigger is precise enough.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does well here: it explains de-duplication by frontmatter name, the source field, and most importantly documents the default COMPACT projection including the concrete size figures (32,480 chars) and the grouped repetition problem. This gives real behavioral richness beyond what any structured field could provide.

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 front-loaded with the core purpose in the first line, then layers specifics in order of importance: sources+precedence, de-duplication identity, source field, and finally the compact projection rationale. Every sentence earns its place, and the concrete char count justifies why the default was chosen. No fluff or repetition.

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 listing tool with a single param and an output schema present, this description is unusually complete. It covers resolution semantics, ordering precedence, de-duplication behavior, the default projection tradeoff, and corrects a likely misreading of 'compact'. The output schema handles return structure, and the description handles all behavioral nuance.

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 fields parameter is self-describing with its compact/all split documented. However, the description adds significant value by explaining the DEFAULT behavior ('compact - trimmed, NOT missing fields'), correcting a likely misinterpretation that compact omits fields. This disambiguation is genuinely useful beyond the bare 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?

The description starts with a specific verb+resource statement ('List every Agent template CC can actually resolve') and goes further to explain the exact scope: which three sources are scanned, the precedence order, and de-duplication logic. This clearly distinguishes it from sibling tools like meeting_template_list and agent_list by focusing on resolution behavior and the subagent_type acceptance match.

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 explains what the tool resolves (templates that subagent_type will accept) and the precedence semantics, giving strong contextual guidance on how results should be interpreted. However, it doesn't explicitly state when NOT to use it or name alternatives like agent_template_recommend, leaving the usage boundaries slightly implicit.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that recommendations are 'live template match against the installed template dirs' ranked by relevance, and explicitly states the team_composition layer is 'static seed, not a live probe' — this distinction between live and static behavior is genuinely valuable and goes beyond what structured data reveals.

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 well-structured with two labeled layers, making the dual-purpose output easy to parse. The sentence explaining the static nature of team_composition is valuable but slightly verbose. Overall concise and front-loaded with the core purpose, though the layer breakdown could be tightened.

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 has an output schema, so return values need not be described. With 2 optional params at 100% schema coverage, the description effectively complements the schema by clarifying the output structure (two layers) and the behavioral distinction between them. Coverage is good for a moderately complex dual-output tool.

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

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

Schema description coverage is 100%, so both parameters (keywords, task_type) already have clear descriptions with examples in the schema. The main description adds the project-type list for task_type (web-app/api-service/data-pipeline/library/refactor/bugfix), which enriches the semantic understanding. However, it doesn't describe how keywords interact with task_type or whether both can be provided together.

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 a specific verb ('Recommend') plus resource ('Agent templates') and adds a distinct secondary purpose (team shape for known project types). It effectively differentiates from siblings like agent_template_list (listing templates) and agent_reuse_recommend (reuse recommendations), establishing its unique job of recommending templates and team composition.

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 explains when the team_composition layer applies ('when task_type names a project type') and explicitly names which project types qualify. It also clarifies that team_composition is 'a static seed, not a live probe', which tells the agent about limitations. It doesn't explicitly name alternatives or exclusions, but the two-layer breakdown gives clear context for when to use versus other recommender tools.

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

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

With no annotations, the description carries the full burden and does disclose a key non-obvious behavior: a manual write is transient and will be overwritten by the next hook/inactivity update. It does not cover permission requirements or the response shape, but the output schema covers returns, so this is solid.

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

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

Three short sentences, front-loaded with the purpose, followed by the behavioral caveat and the usage restriction. No filler, every sentence earns its place.

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

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

For a two-parameter mutation tool with an output schema and no annotations, the description supplies the one thing structured fields cannot: that the change is transient and easily overwritten. Auth/permission details are the only real 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% and both parameters are fully documented in the schema (including enum-like status values and the note that agent_id is the id from agent_list, not the name). The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Update an Agent's running status') and, crucially, distinguishes this manual operation from the automatic status maintenance performed by hook events and inactivity. An agent can immediately tell this apart from the auto-maintained status path.

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 scopes usage: the status is normally maintained automatically, and this tool should be used 'only to correct a status the hooks left stale.' Both when-to-use and when-not-to-use are stated, along with the reason (the next automatic update overwrites the manual write).

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

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

With no annotations, the description carries the full burden and does so well: it discloses the user_present/hint return signals and their 15-minute lookback window, the 14-day expiry of unanswered items, and that expiry affects status only (never deletion). These are non-obvious lifecycle and side-effect facts an agent needs.

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 routing rule is front-loaded and every sentence adds a distinct rule (when to use, exclusion, resolve path, expiry). Slightly dense, but 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, yet the description still supplies the lifecycle and return-signal context an agent needs to route and later resolve items. Nothing required to call or follow up on this tool is missing.

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

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

Schema coverage is 100% across all 6 parameters, so the schema already documents title, options, urgency, tags, description and recommendation. The description adds no format or constraint detail 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?

States a specific verb+resource (park a decision for the user) plus the critical scope condition (only when the user is NOT in the conversation). An agent can distinguish it from briefing_resolve and briefing_list 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 enumerates the situations that qualify (autonomous /loop work, background workflows, another session's findings, sub-agent reports) and the exclusion (if the user is present, ask directly instead). It also names the follow-up tool, briefing_resolve, and the condition that triggers it.

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

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

With no annotations, the description must convey all behavioral traits. It mentions that no action is needed after dismissal, but lacks detail on side effects, required permissions, or reversibility. This is adequate but minimal.

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 that immediately conveys the tool's purpose. Every word is necessary, and there is no 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?

Given the simplicity of the tool (one parameter, output schema exists), the description is too terse. It does not explain what happens after dismissal (e.g., state change, visibility) or how it differs from related tools. The phrase '(no action needed)' causes ambiguity rather than clarity.

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 describes the only parameter 'briefing_id' as 'Briefing item ID'. The description does not add additional meaning or context about how the parameter is used, so it does not go beyond the schema.

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

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

The description clearly states the action (dismiss) and the object (Leader Briefing item), distinguishing it from sibling tools like briefing_resolve and briefing_list. The verb 'Dismiss' is specific and 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?

No explicit guidance on when to use this tool versus alternatives such as briefing_resolve. The phrase '(no action needed)' hints at a scenario but does not clearly define when dismissal is appropriate.

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

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

With no annotations, the description carries the full disclosure burden. It usefully reveals the default pending-only filter and the shape of returned items (project_id and tags), but says nothing about ordering, pagination, or permission requirements for reading briefing items.

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?

Short and front-loaded: the verb/resource lead, followed by the default behavior and a note about item contents. Every sentence is relevant, though the second sentence leans on information the schema already provides.

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 parameters are fully documented in the schema. Combined with the stated default behavior, the definition is complete enough for an agent to call the tool correctly; only cross-sibling routing guidance is thin.

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 tag, status, and project_id in detail (including the 14-day expiry and "current" semantics). The description's "narrowed to one project and/or one topic" sentence is a light gloss that adds no detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List Leader Briefing items") that an agent can act on directly. It does not, however, explicitly differentiate itself from siblings like briefing_add, briefing_resolve, or briefing_dismiss beyond the implicit list-vs-mutate distinction.

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 explains the default behavior ("Default shows pending items for user review") and hints at narrowing by project/tag, which implies usage. It never explicitly states when to use this tool versus briefing_resolve, briefing_dismiss, or the many other list_* siblings, so the guidance is only implied.

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

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

With no annotations, the description carries the full burden but does disclose a meaningful, non-obvious side effect: the answer is also written as a decision event (decision.briefing_resolved). This tells the agent the call is a mutation with cross-cutting persistence. It still omits failure modes, idempotency, and whether closing is 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?

The purpose is front-loaded in the first sentence, followed by when-to-call guidance and the side effect. The phrasing 'in whatever session that happens' is slightly loose, but every sentence carries 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?

An output schema exists, so return values need not be explained. The description covers purpose, timing, cardinality, and the persistence side effect. It is nearly complete, missing only sibling routing (briefing_dismiss) and edge-case 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 coverage is 100%, so both parameters are already documented in the schema (resolution = user's decision in own words; briefing_id = briefing item ID). The description adds no syntax, format, or addressing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Record the user's answer to a pending decision and close it.' This is unambiguous and distinct from lookup siblings like briefing_list. However, it does not explicitly differentiate itself from the closest sibling, briefing_dismiss, which also affects a briefing item.

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 timing guidance ('Call it the moment the user answers, in whatever session that happens') and a cardinality rule ('one call per answered item'). It stops short of naming exclusions or alternatives such as briefing_dismiss, so it gives context but no routing between 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?

No annotations are provided, so the description carries the burden. 'Get' implies a read-only query and the note on the two name forms is a useful matching behavior, but it discloses nothing about scan scope (which channels/time range) or result ordering that an agent calling this would benefit from. Adequate but with clear gaps.

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, purpose front-loaded and the matching note following it. No wasted text; nothing needs trimming.

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 explained, and both simple parameters are fully documented. The description is nearly complete; the only omission is the scope of the scan (all channels vs. a specific one), which would matter for a mention-search 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 schema already documents both limit and agent_name, including the note that the '@' prefix is optional. The description's sentence about the two notations simply repeats what the schema states, so it adds no meaning beyond the structured field. 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?

States a specific verb (Get), resource (channel messages), and scope (those mentioning a specific agent). This clearly distinguishes it from read-oriented siblings like channel_read and channel_unread, though it does not name those siblings explicitly.

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

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

Usage is implied: an agent needing messages that reference it would reach for this. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives such as channel_read or channel_wait, 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?

With no annotations, the description carries the full burden and discloses the single most surprising behavioral trait: reading does not clear unread, and clearing requires an explicit ack call. It omits other behavioral context such as auth/permission requirements or rate limits, but the critical non-obvious behavior is covered.

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 core purpose, then adds the incremental-pull capability, then the ack workflow — a sensible ordering with little wasted text. The switch to another language in the final sentences is a minor consistency cost but the content still 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?

An output schema exists so return-value description is unnecessary, and the description supplies the key behavioral caveat (does not clear unread) plus the ack follow-up, which is what an agent most needs to call this correctly. Completeness is strong, with only minor gaps around permissions/pagination left to structured fields.

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 are already documented, making 3 the baseline. The description adds a light conceptual framing for 'since' (incremental pull), but does not extend semantics for 'limit' or 'channel' 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 and resource ('Read messages from a channel') and immediately disambiguates from the closely-named sibling channel_read_ack by declaring it is a pure read that does not clear the unread badge. The agent can tell this apart from the ack and unread siblings without opening a schema.

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

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

Gives a concrete use condition for the 'since' parameter (incremental pull of only new messages) and states the required follow-up workflow (call channel_read_ack separately to clear the badge), which is genuine when/how guidance. It stops short of naming alternatives like channel_unread, channel_wait, or channel_mentions or stating when not to use this 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?

With no annotations provided, the description carries the behavioral burden and it does disclose key traits: the operation is idempotent and monotonic, and passing a time earlier than or equal to the current watermark is a no-op returning advanced=false. This is exactly the kind of behavioral context an agent needs. It stops short of describing permissions/authorization or any side effects beyond the watermark update.

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, purpose front-loaded in the first clause and the idempotency/monotonicity behavior stated second. Every sentence earns its place with zero 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?

An output schema exists, so return values (advanced=false) need not be explained at length, and the 100%-covered parameter schema is thorough. The description covers purpose and the core idempotency behavior. Only minor gaps remain around authorization/who may ack as an actor, but the essential information for a correct call is present.

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 already documents all four parameters, including the critical warning against passing 'now' with pagination. The description only reinforces the meaning of last_read_at (传入时间) implicitly. Baseline 3 is appropriate 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 states a specific verb and resource: advancing a channel's read watermark (已读水位) to the last message actually read and clearing the corresponding unread. This is clearly distinct from sibling read tools (channel_read, channel_unread, channel_mentions), which the parameter descriptions further tie it to. An agent can identify this as the ack/advance-watermark action 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?

Usage is implied — use this after you have actually read messages, to advance the watermark. It does not explicitly say when to prefer it over a hypothetical alternative, nor state prerequisites (e.g., that you must have read the messages first), though the last_read_at parameter notes reinforce correct usage. Implied context only.

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

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

With no annotations, the description carries the burden and adds useful behavioral context: cross-team broadcasting and the rule that mentions accept both bare names and '@name' and that unread detection honors both. However, it omits auth/permission needs, persistence guarantees, and error behavior for a send operation.

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

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

Front-loaded with the core action and then structured as a compact format list. The trailing sentence switches languages (English then Chinese) which is slightly jarring, but every line carries information.

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

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

Covers channel formats, mention semantics, and broadcast scope; an output schema exists so return values need not be explained. Gaps remain around permissions and delivery/persistence behavior for a send tool with no annotations, but the essentials are present.

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% (baseline 3), and the description still adds value by explaining what each channel prefix means and clarifying the mentions equivalence rule (bare name vs '@name'), beyond the single schema examples.

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 ('Send a message to a channel') and then enumerates the three channel target formats with what each means (team-specific, project-wide, global broadcast). An agent can distinguish this from channel_read/channel_mentions 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?

Usage is implied by the purpose plus the channel-format list, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as meeting_send_message or channel_read for reading instead of sending. The agent must infer the context of use.

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

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

With no annotations provided, the description carries the full behavioral burden and does so: it discloses that the operation is non-mutating (no watermark rows written), defines unread precisely (mentions matching reader, message belongs to project, newer than the channel's read watermark), defines the no-watermark case as 'everything unread', and warns that truncated=true means the scan hit a cap and the counts are undercounted rather than complete.

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, then read-only semantics and the ack alternative, then the unread definition and truncation caveat. Dense but every clause carries information; the only minor waste is enumerating return fields that the output schema already covers.

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 a read-only aggregation tool: purpose, read-vs-ack semantics, the unread definition and edge case, and truncation behavior are all present. An output schema exists, so restating the return fields is slight redundancy rather than a gap.

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

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

Schema description coverage is 100%, so both reader and project_id are already documented in the schema (including the session_id warning and the empty-string default behavior). The description adds the reader-centric unread definition but nothing further about parameter syntax or formatting, 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+resource: per-channel unread counts for a given reader within a project, with a parenthetical telling the agent exactly what each entry answers (who is calling, how many, latest excerpt). This is plainly distinguishable from siblings like channel_read_ack (clearing) and channel_read (reading a channel).

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 frames this as a pure read that neither clears unread nor writes a watermark row, and names the correct alternative for resetting: channel_read_ack. The when-to-use (checking who mentioned you) and the when-to-use-something-else case are both 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?

With no annotations, the description carries the full burden and does so: it declares this is read-only and does not auto-ACK, describes timeout/cancel/connection-failure endings, warns that local-only client timeouts are invisible to the server, and even gives the MCP-request timeout formula (timeout_seconds + 4*io_timeout_seconds + 5). This is exactly the operational context an agent needs to invoke it safely.

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

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

Four tight paragraphs, front-loaded with purpose, then behavior, then the actionable timeout budget rule, then return/error semantics. Despite the density every sentence carries distinct information, so nothing reads as padding.

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

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

For a 9-parameter blocking tool with no annotations but with an output schema, the description covers what the schema and output cannot: read-only guarantee, blocking lifecycle, cancellation/failure endings, timeout composition, and durable error behavior on bad cursors. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains how timeout_seconds and io_timeout_seconds compose into the caller's overall timeout budget, clarifies that cursor is the resume mechanism (not a timestamp), and states that an invalid cursor errors loudly rather than silently skipping pages.

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 clause states a specific verb (等待) and resource (指定对端的新消息) plus the mechanism (先补读, 随后 WebSocket), which cleanly separates it from poll-style siblings like channel_read / channel_unread / channel_mentions. An agent can tell this is a blocking subscription-wait tool without opening the schema.

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

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

It gives clear context on when the tool is appropriate (waiting for new peer messages, replay-then-subscribe) and important exclusions (cannot wake an already-finished Desktop turn, timeout does not auto-reopen the wait). However it never names a sibling alternative for the non-blocking case, so the routing guidance 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?

No annotations are provided, so the description carries the full burden. It transparently explains the multi-team behavior — that a project routinely has several teams simultaneously (session container team plus one per Workflow run) — and clarifies the 3-tier priority resolution for the singular 'team' field. This is meaningful behavioral context beyond a generic read.

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?

Well-structured and front-loaded. The first sentence states the core purpose, followed by the infrastructure rationale, then clarifies the important teams vs team distinction, and ends with a concise return summary. Every paragraph earns its place with no filler.

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

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

Given the tool has an output schema, the description doesn't need to enumerate return values in detail. It's a read-only context retrieval tool with no parameters, and the description adequately handles the one subtle behavioral nuance (multi-team vs singular team) that could confuse callers. The role as infrastructure is well explained.

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

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

The tool has 0 parameters with 100% schema coverage, so the baseline is 4 per the rubric. The description confirms it takes no parameters and describes the return structure (Context dict with project/team/teams/agents), adding value about what the caller should expect.

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 gets the current active OS context including active project, teams, and member list. It distinguishes itself by establishing itself as 'the infrastructure for all simplified operations' and explains its role in auto-filling parameters for other tools, which differentiates it from 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?

The description clearly explains when to use this tool — as a first call to establish context before using simplified operations. It explains that other tools (like Leader) use it to auto-fill parameters. However, it doesn't explicitly state when NOT to use it or name alternatives, though the value proposition is clear enough given its foundational role.

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

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

With no annotations available, the description carries the full burden and does well: it discloses the 4-round debate mechanics, the function of each role, exactly what is returned (role assignments, round rules, Round 1 starter prompt) and — critically — the negative behavior that no dispatch_plan is produced so nothing is auto-spawned. The absence of auth/permission notes is a minor gap for a tool that appears to create structured state rather than mutate data destructively.

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, then a scannable role list, then the return-value caveat and the alternative in a single closing sentence. No filler sentences; every line carries either scope, mechanism, or routing 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?

For a moderately complex orchestration tool with an output schema present, the description covers purpose, debate structure, return semantics, and the alternative tool. Return-value details are correctly left to the output schema, so nothing an agent needs to invoke 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 100%, so all six parameters (judge, critic, team_id, advocate, file_path, change_description) are already documented with defaults. The description adds only thematic meaning about what each role does in the debate, which the schema's own role descriptions largely cover. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Start a debate-style code review') with an explicit scope ('for a specific file or change'). It immediately enumerates the three roles and the 4-round shape, so an agent can distinguish it from debate_start, meeting_create, and other review tools 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 states when to use this tool versus the alternative: this one returns no dispatch_plan so participants are spawned by hand, and it names meeting_create(template="debate", participants=[...]) for ready-to-paste spawn calls. That is a concrete when/when-not routing instruction.

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

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

With no annotations, the description carries the burden and does disclose a non-obvious behavioral trait: it returns role assignments and round rules but no dispatch_plan, so participants are spawned manually. It does not address persistence (whether a meeting record is created), permissions, or reversibility, leaving some gaps for a state-changing 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?

Front-loads the one-line purpose, then uses a scannable bulleted round breakdown, then closes with the alternative. Every section earns its place; the four-round list is somewhat verbose but conveys genuinely distinct information.

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

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

An output schema exists, so return values need not be restated, and the description correctly focuses on the round structure and the missing dispatch_plan. It leaves unstated whether a persistent meeting is created or what happens on partial failure, minor gaps for a 5-param orchestration tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the judge default and team_id. The description adds the semantic framing of advocate/critic/judge roles but no format or syntax detail beyond what the schema provides, so baseline 3 is 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?

States a specific verb and resource (start a structured 4-round debate meeting) and enumerates exactly what that entails round by round. An agent can distinguish it from siblings like meeting_create, debate_code_review, and ecosystem_trigger_debate from the description alone.

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 names the alternative and the condition that selects it: 'For ready-to-paste spawn calls use meeting_create(template="debate", participants=[...]) instead.' It also states the practical consequence of choosing this tool – that each participant must be spawned by hand.

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

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

No annotations provided, and the description does not disclose behavioral traits such as side effects (none expected for a query), auth requirements, rate limits, or pagination behavior. The word 'Query' hints at read-only, but not explicitly confirmed.

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, clear sentence with no wasted words. It front-loads the purpose and provides concrete examples efficiently.

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 presence of an output schema and full parameter descriptions, the description is nearly complete. It could mention ordering (e.g., chronological) but the schema covers limit and filtering. Adequate for a query tool.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds value by explaining what kinds of decisions are captured (task assignments, approach selections, scheduling), which enriches the meaning of the event_type parameter beyond the schema.

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

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

The description clearly states the tool queries the team decision log and provides examples of content (task assignments, approach selections, scheduling decisions). However, it does not explicitly differentiate from sibling tools or mention its scope relative to them.

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 tool vs alternatives, nor any exclusions or prerequisites. The description implies a query context but lacks explicit usage directions.

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

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

With no annotations, the description carries the full behavioral burden and discloses significant traits: it reads the task's valid memos, compares with similar successful tasks in the same team, returns fix suggestions, and records a task.failure_diagnosed event as a side effect. It also warns that the tool is frozen and no longer developed. It does not cover permissions, error behavior, or rate limits, so it is not fully exhaustive.

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 front-loaded with the tool's purpose and then adds method, side effect, and usage in short sections. Each sentence contributes useful information, and the frozen status is clearly separated. It is slightly longer than strictly necessary but not wasteful.

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

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

Given the simple one-parameter input schema, the existence of an output schema, and the lack of annotations, the description provides enough context for correct invocation: it explains the diagnostic process, side effect, and when to use it. Minor gaps around error handling or disabled status remain, but the core information is complete.

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 only one required parameter, task_id, and the input schema already documents it at 100% coverage as 'ID of the failed or stuck task'. The description adds no parameter-level syntax, format, or constraint details beyond what the schema provides. Baseline 3 is appropriate when the schema fully covers the sole parameter.

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

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

The description states a specific verb+resource ('auto-diagnose why a task failed') and outlines the method: reads memos, compares to successful tasks, and suggests fixes. It clearly tells an agent what the tool does. However, it does not explicitly distinguish itself from the sibling failure_analysis tool, which could overlap.

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

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

It gives explicit usage context: 'Use this when a task fails or gets stuck to quickly understand root cause without manually reading through all memo records. It also notes the tool is frozen but still callable. No when-not conditions or alternative tools are named, so there is room for improvement.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the persistent side effect (stored in ~/.claude/data/ai-team-os/dismissed_projects.json), that the choice is irreversible ('no tool reverses'), and explicitly negates destructive behavior ('No project is created, changed, or deleted'). This is exactly the behavioral context an agent needs before calling.

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 action and its headline effect in the first sentence, followed by two short paragraphs that cover the trigger context, persistence location, irreversibility, and non-effects. 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 no explanation, and the description covers everything else an agent needs: trigger condition, persistence location, irreversibility, and the absence of destructive side effects. Complete for a low-complexity, single-optional-parameter 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% and the single cwd parameter already documents the empty-string default meaning. The description mentions 'current cwd' consistently but adds no format, path-resolution, or traversal detail beyond what the schema provides, so the 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?

Names a specific action (mark cwd as dismissed for project registration) and a specific resource (the current working directory), and immediately distinguishes itself from siblings like project_create/project_update by stating no project is created or changed. An agent can tell it apart from the similarly named briefing_dismiss and notice_dismiss 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 clearly gives the triggering context — the session-start briefing asking whether to register an unregistered working directory — and the resulting condition (it stops asking for that directory, and the Dashboard notice is dismissed). What is missing is an explicit named alternative, e.g. 'to register instead, use project_create', so the when-not branch is only implied.

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

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

No annotations exist, so the description carries full burden. It discloses behavioral traits beyond the schema: state transitions (stage_status changes), row completion, and UI retry for failure. This provides comprehensive 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?

The description is efficiently structured with two clear paragraphs covering success and failure paths. It is front-loaded with the primary purpose. Every sentence adds value, though it could be slightly more concise.

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 no annotations and a moderate number of parameters (4), the description fully covers the tool's behavior, state transitions, and parameter usage. The output schema exists but is not shown, so the description does not need to elaborate on return values. It is complete for agent understanding.

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 baseline is 3. The description adds value by explaining the conditional relationship between architecture_md and error_message, and reiterates the length requirement (800-1500 characters). This enhances understanding beyond the schema alone.

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 as 'Stage 1 writeback — submit architecture_md OR report failure.' It distinguishes the success and failure paths explicitly, which differentiates it from sibling ecosystem_apply_* 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?

The description provides explicit guidance on when to use the success path (pass non-empty architecture_md) versus the failure path (pass empty architecture_md and error_message). It does not compare to other tools or specify exclusions, 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals constraints (non-empty fields, enum values) and the intended state transition ('advance to debated'). However, it does not describe side effects, authorization requirements, error conditions, or what happens on success/failure. This leaves significant gaps for a write operation.

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

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

The description is extremely concise—just two sentences. The first sentence states the core purpose, and the second provides critical usage notes. Every phrase adds value; there is no fluff or redundancy. It is well-structured for quick comprehension.

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 presence of an output schema and full parameter descriptions, the description provides all necessary context: the tool's role in a multi-stage process, required constraints, and enum options. It is sufficiently complete for an agent to understand how and when to invoke this 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%, providing baseline descriptions for all 6 parameters. The description adds value by clarifying operational constraints: at least one of risks_md, learnings_md, integration_md must be non-empty, and integration_recommendation is an enum with specific values. This supplements the schema beyond mere 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?

The description clearly states the tool's purpose: 'Stage 2 writeback — submit debate conclusion to advance to debated.' It uses a specific verb ('submit') and resource ('debate conclusion'), and implies a state transition. This distinguishes it from sibling tools like ecosystem_apply_architecture_md, which have different purposes.

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

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

The description explicitly provides a usage constraint: 'At least one of risks_md / learnings_md / integration_md must be non-empty.' It also notes the enum values for integration_recommendation. However, it does not give guidance on when to use this tool over alternatives like other ecosystem_apply_* tools, missing an opportunity for stronger differentiation.

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 key behavioral effects: it writes specific fields (quality_score, quality_notes, reviewed_by, reviewed_at) and clears claimed_by to allow other workers to pick up the next row. With no annotations provided, this provides sufficient transparency for a simple update operation.

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

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

The description is two sentences with no unnecessary words. The first sentence states the high-level purpose, and the second provides specific details about the fields and lock release. Every sentence adds 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?

Given there is an output schema (context indicates present), the description does not need to explain return values. It covers the essential behavioral effects and side effects. It does not mention error conditions or idempotency, but for a straightforward update tool, it is largely complete.

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 baseline is 3. The description mentions some fields (quality_score, quality_notes) that are parameters, but adds minimal additional meaning beyond the schema. It also mentions reviewed_by and reviewed_at, which are not input parameters, potentially causing confusion.

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 'Submit quality review result and release the claim lock', which specifies the verb (submit/release) and the resource (quality review/claim lock). It distinguishes from siblings like ecosystem_claim_review (which claims) and ecosystem_release_claim (which only releases) by combining both actions.

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?

While the description implies the tool is used after a review is completed and to release the lock, it does not explicitly state when to use it versus alternatives (e.g., using ecosystem_release_claim instead if no review submission is needed) or mention any prerequisites or conditions.

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

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

No annotations provided, so description carries full burden. It explains effects (persist summary, advance stage, route failures) and mentions rate_limit_remaining for 403. However, missing details on idempotency, auth requirements, or consequences of repeated calls—adequate but not thorough.

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?

Well-structured with clear sections for success and failure paths. Front-loaded with main purpose. Efficient, though could slightly condense the error_kind enumeration.

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?

Covers the two main workflows and parameter roles. Output schema exists (not shown) so return values are covered. Lacks mention of prerequisites or whether the agent should call this directly vs. it being system-invoked—but sufficient for most use cases.

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%, but description adds significant value by grouping parameters into success/failure paths, explaining the role of deep_review_id, and listing valid error_kind values. This goes beyond 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?

Clear statement: 'Stage 0 worker callback: write back a shallow summary OR report a failure.' Distinguishes success and failure paths, and the name implies its role among ecosystem sibling 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?

Explicitly describes when to use success vs. failure path, lists valid error_kind values. Lacks explicit 'when not to use' or comparison with other ecosystem apply tools, but context from name and description suffices.

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

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

With no annotations the description carries the full burden, and it does disclose a real behavioral trait beyond the schema: the claim is a 60-minute lease that expires and lets another worker take the row. It does not cover what happens when the queue is empty, whether the claim must be explicitly released (ecosystem_release_claim exists), or any permission requirements.

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

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

Four short sentences, front-loaded with the action, then selection criteria, then return value, then lease behavior. Every sentence carries information and none is redundant 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?

An output schema exists so return values need not be explained, and the description sufficiently covers the claim semantics and lifecycle caveat. The remaining gap is edge-case behavior (empty queue, explicit release, claim renewal), which an agent working a review queue would benefit from knowing.

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% for both parameters, so the schema already documents worker_id and min_stars; the description adds no syntax or filtering detail beyond that (it never even mentions min_stars). Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Claim the next shallow_done repo for quality review') and then specifies the exact selection predicate (stage_status='shallow_done', no quality_score, no active claim), which cleanly separates it from siblings like ecosystem_claim_shallow and ecosystem_apply_quality_review 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?

The queue semantics and the 'so the reviewer can evaluate quality' clause give clear operational context for when to call it. However, no alternative is named (e.g. ecosystem_claim_shallow vs this quality-review claim) and there is no when-not guidance, so it stops short of the 5-level routing statement.

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

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

With no annotations at all, the description carries the full behavioral burden and delivers: it discloses atomicity (only one worker wins, others get {"claimed": false}), the lease duration (60 minutes), and reclaim behavior for unfinished rows. This is exactly the runtime semantics an agent needs and could not get from the 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?

Four sentences, each front-loaded and earning its place: action, atomicity guarantee, lease semantics, and what comes back. No filler or redundancy.

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

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

Output schema exists, so return values need not be re-explained, yet the description usefully pre-empts a follow-up call by listing the returned fields. Combined with the lease and atomicity disclosure, nothing an agent needs to invoke and reason about this tool is missing.

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

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

Schema description coverage is 100% and there is only one parameter (worker_id), already documented in the schema. The description implies multi-worker contention but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (claim), a specific resource (next queued repo), and a scope (shallow scanning, stage_status='queued'). This clearly distinguishes it from the deep-review claim sibling, so an agent can pick the right one from the name and description alone.

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 tells the agent this is for pulling queued rows and even notes that no separate ecosystem_repo_get call is needed after it, which is useful context. But it never explicitly contrasts with ecosystem_claim_review or states when this shallow claim is preferred over a deep-review claim, leaving that inference to the reader.

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

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

No annotations provided, but the description fully discloses behavioral traits: it advances stage_status to shallow_failed, derives status to failed, adds a cancellation note, and explains sub-agent behavior. This covers all necessary transparency beyond what annotations would provide.

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?

Description is brief (4 lines), front-loaded with the primary action, and every sentence adds value (state condition, effects, sub-agent behavior). No unnecessary words.

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?

Input schema is simple and fully covered. An output schema exists (per context) but is not shown; per rules, description need not explain return values. The description covers the cancellation flow adequately. Minor gap: could mention if any side effects, but sufficient for a cancel action.

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 has one parameter (deep_review_id) with full description, so schema coverage is 100%. The description does not add semantic detail beyond 'EcosystemDeepReview.id', which is already in 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?

Description clearly states the tool cancels an in-flight deep-review (stage_status='queued'), using a specific verb and resource. It distinguishes from sibling tools like ecosystem_deep_review_request and ecosystem_deep_review_status.

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 specifies the condition for use (stage_status='queued'), providing clear context. Does not explicitly state when not to use or name alternatives, but the condition is sufficiently 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?

No annotations are provided, so the description bears the full burden. It does usefully disclose sort order (newest-first) and that filtering is optional, but says nothing about permissions, pagination beyond the limit parameter, or total counts. An output schema exists, so return-shape explanation is not required, but behavioral context is thin.

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

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

A single front-loaded sentence with no wasted words; verb, resource, ordering, and the optional filter all appear immediately.

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

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

For a two-parameter, non-destructive list tool with a fully documented schema and an output schema, the description covers the essentials. The main gap is absent guidance on when to prefer this over sibling listing/status tools.

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 limit and status documented in depth (including the 'running' legacy nuance), so the schema does the heavy lifting. The description only restates that a status filter exists, adding no meaning beyond the schema 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?

States a clear verb (List) and resource (deep-reviews) plus the ordering semantics (newest-first) and the optional filter. It does not distinguish itself from nearby siblings like ecosystem_deep_review_status or ecosystem_deep_review_request, leaving the agent to infer that this is the enumeration 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?

No when-to-use guidance and no mention of alternatives. The agent cannot tell from the description why it should call this rather than ecosystem_deep_review_status or ecosystem_repo_events when looking for review data.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the created row, its stage_status='queued', the derived read-only status column, the embedded dispatch_prompt, the watchdog that flips stage_status to shallow_failed on timeout, and the Leader's responsibility to spawn the sub-agent. This is rich, non-obvious lifecycle 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?

Purpose is front-loaded in the opening sentence and the rest details the lifecycle. It is fairly dense and includes implementation-level naming (stage_status codes), which is useful but slightly verbose. Overall efficient and well-structured.

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 mutation tool with a rich output schema present, the description covers creation semantics, status derivation, timeout behavior, and follow-up responsibility well. Only the boundary against the batch sibling is unaddressed, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents repo_id, agent_id, priority, and timeout_minutes. The description adds meaning to timeout_minutes by tying it to the watchdog auto-fail, but adds nothing about agent_id or priority beyond the schema.

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

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

The first sentence states a specific verb (Queue) and resource (deep-review for a repo) plus the return value (dispatch prompt). It is clearly distinguishable from siblings like ecosystem_deep_review_request_batch, ecosystem_deep_review_status, and ecosystem_deep_review_cancel.

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 (queueing a deep review and then having the Leader spawn the sub-agent), but never states when to choose this over alternatives such as the batch variant or the status/cancel siblings. Usage is inferred rather than guided.

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

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

With no annotations provided, the description carries full responsibility and does disclose the mutable side effects: it creates an EcosystemDeepReview row per candidate. It also clarifies the division of responsibility ('Leader is responsible for actually spawning each agent via the Agent tool'), making the batch-nature and delegation behavior transparent beyond what schema reveals.

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 well structured with a clear Stage-1 label, distinct sentences covering pipeline inputs, side effects, and downstream handoff. Every sentence earns its place; there's no filler or redundancy. It is front-loaded with the primary purpose.

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 is complex (orchestration, batch creation, sub-agent spawning) but the description covers the essential flow: candidate selection criteria, row creation, output payload type, leader responsibility, and downstream write-back tool. Combined with a 100% schema coverage and an existing output schema, this is complete for an orchestration tool of this 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 coverage is 100% so the baseline is 3. The description adds value by clarifying the AND-tag semantics and noting empty list returns 400 (behavioral constraint not obvious from schema alone). The description reinforces that research_goal is injected into each sub-agent prompt, though the schema already says this. Slight redundancy, but the tag semantics clarification pushes it above 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 states a specific verb+resource: 'Queue architecture-analysis dispatches for tag-filtered candidates' and describes the pipeline with an explicit Stage label. It clearly identifies inputs (active+shallow_done profiles with AND tag semantics), the output (DispatchIntent payloads), and differentiates this from sibling ecosystem tools by naming the downstream write-back target (ecosystem_apply_architecture_md).

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 clear operational context: it pulls specific profile states (active+shallow_done), uses AND tag semantics, and names the downstream tool each agent calls. However, it does not explicitly state when NOT to use this versus alternatives like ecosystem_deep_review_request (singular), ecosystem_scan, or ecosystem_trigger_debate, leaving some comparison ambiguity.

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

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

No annotations exist, so the description must disclose behavior. It only states the basic lookup action, with no mention of side effects, permissions, or guarantee of read-only operation. For a lookup tool, the description is insufficiently transparent.

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 directly states the action. It is front-loaded and efficient, though it could be slightly expanded for clarity.

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 existence of an output schema, return values need not be explained. However, the description lacks any context about prerequisites, error cases (e.g., no deep review found), or relation to other deep review tools. For a simple lookup, it is minimally complete.

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 100% schema coverage, the baseline is 3. The description mentions repo_id but adds no semantic value beyond the schema's description 'EcosystemRepoProfile.id.' It does not explain how to obtain or format the ID.

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 looks up the most recent deep-review for a given repo, using a specific verb and resource. While it differentiates from siblings like ecosystem_deep_review_list (which lists all) by focusing on a single most recent result, it does not explicitly compare itself to siblings.

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

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

No guidance is provided on when to use this tool versus alternatives such as ecosystem_deep_review_list or ecosystem_deep_review_request. The description lacks context for when this lookup is appropriate.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: the diff is computed dynamically rather than read from storage, events are grouped by type into named categories, and only scans that record events are counted. It does not state permission requirements or cost/performance characteristics, but the core behavioral model is conveyed.

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 what-is-returned statement is front-loaded, followed by the grouping detail, the counting caveat, and the sibling differentiation. Four sentences with little waste, though the parenthetical pointer to ecosystem_repo_events and the sibling note could be tightened.

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 documentation is not required, and the description covers scope, counting rule, and sibling routing. Nothing critical for correct invocation is missing, though prerequisites for the underlying event log (e.g., which scans populate it) are only cross-referenced.

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 from_date and to_date documented as inclusive YYYY-MM-DD bounds, so the schema already carries the semantics. The description adds only the implied period framing ('time-period diff'), which does not extend beyond the schema.

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

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

States a specific verb and resource ('Return a time-period diff computed dynamically from the per-repo event log') and names the sibling it is not ('ecosystem_index_diff_latest instead returns the stored diff'). An agent can distinguish this from ecosystem_repo_events and ecosystem_index_diff_latest without opening a schema.

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

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

Names the alternative tool (ecosystem_index_diff_latest) and the distinguishing condition (dynamic vs. stored last-run diff), and points to ecosystem_repo_events for the underlying events. It stops short of an explicit 'use this when you want a live period comparison rather than the cached snapshot', so it is clear context rather than a full when/when-not rule.

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

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

With no annotations, the description carries the full burden and does most of it well: it discloses that dry-run previews are never persisted, that a 404 maps to an unimplemented endpoint ('P0.4 will implement'), and it explicitly defines success=True vs success=False semantics including the case where diff is None. That is genuinely useful non-obvious behavior; only auth/permission caveats are absent.

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 lead sentence is well front-loaded, but the large 'Returns' block enumerates field-by-field payload shapes that an output schema already supplies, adding bulk without adding much interpretive value. Some of that space could have gone to sibling differentiation instead.

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 parameterless read with an output schema, this is close to complete: the dry-run non-persistence rule and the success-flag semantics are the pieces an agent actually needs and would not otherwise get. Auth/permission requirements remain 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 tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. It correctly gives no parameter guidance because none is needed.

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 ('Fetch the latest IndexDiff snapshot for the current project') and pins the exact endpoint, so the agent knows precisely what is being retrieved. It does not explicitly differentiate itself from the sibling ecosystem_diff_period or ecosystem_index_update, which would be the natural confusions.

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 when this is useful by explaining that only persisted non-dry-run diffs appear here, which helps an agent understand what it will get. However, it never says when to call this versus ecosystem_diff_period or ecosystem_index_update, leaving the sibling routing 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?

With no annotations, the description carries the full burden and does well: it names the config source (min_stars, focus_topics, alert_max_new_per_scan), the full pipeline order, and precisely which tables are written (ecosystem_repo_profiles / ecosystem_index_diffs / ecosystem_status_changes) and that dry_run=True touches none of them. It lacks failure/rate-limit behavior, so it is not 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 the core action, then the pipeline and the dry_run boundary. The pipeline enumeration is long but each stage is informative; the only mild noise is the escaped-backtick formatting and the redundant restatement of the write behavior between the prose and the 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. Given no annotations and a side-effecting tool, the description adequately covers configuration source, pipeline stages, and the write/no-write boundary — everything an agent needs to call it safely.

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

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

Schema coverage is 100% and there is only one parameter, so baseline is 3. The description goes beyond the schema by spelling out that dry_run=False persists profile upserts + index_diff + status_changes across three named tables, adding real semantic weight to the flag.

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 ('trigger ecosystem index update') and immediately summarizes the behavior ('runs scanner + computes diff'). It does not explicitly differentiate itself from near-siblings like ecosystem_scan, ecosystem_refresh, or ecosystem_index_diff_latest, so it falls just 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?

No explicit when-to-use/when-not guidance relative to the many ecosystem_* siblings (scan, refresh, scan_periodic). Usage is only implied through the dry_run default (simulate first) and the description of what a full run does, which is enough to infer intent but leaves alternative selection to the agent.

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

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

With no annotations, the description carries the burden and does well: it discloses the mutation (writes debate_meeting_id), the scope (onto every review in review_ids), the prerequisite ordering, and the downstream consumer (meeting_conclude's ecosystem_writeback). It omits failure behavior, overwrite/idempotency semantics, and any permission requirements.

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

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

The role and the effect are front-loaded ('Stage 2 helper', then 'writes debate_meeting_id onto every review'), followed by the sequencing detail. Three tight sentences with no filler, though the backtick-heavy formatting is slightly noisy.

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 prerequisite, the write target, and the consumer. For an unannotated mutation tool it could say more about failure or re-invocation behavior, but an agent has enough 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% and the schema already documents both parameters, including their provenance (debate_start, ecosystem_trigger_debate). The description only restates that meeting_id is linked to review_ids, adding no format or syntax 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 (link) and the exact resources involved (a debate_start meeting id onto review rows), and positions itself as 'Stage 2' of a named workflow. An agent can distinguish it from debate_start, ecosystem_trigger_debate, and meeting_conclude 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?

Gives explicit timing: 'Called immediately after debate_start succeeds,' which tells the agent the triggering condition and prerequisite. It does not state when not to call it or what to do if debate_start fails, but the sequencing guidance is clear enough to route correctly.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a mutation ('link') but discloses nothing about side effects, idempotency, permissions, or error behavior, leaving significant gaps for a write operation.

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

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

Extremely concise single sentence with no wasted words. The purpose is front-loaded after a brief stage label, making it easy to scan.

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 simple two-parameter tool, full schema coverage, and an output schema, the description is minimally adequate. However, the lack of usage guidance and behavioral disclosure leaves it incomplete for an agent navigating many sibling tools.

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 parameters documented in the schema, so the baseline is 3. The description adds no meaning beyond the schema's parameter 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?

The description states a specific verb and resource: 'link integration task id back to review row.' This is clear and not a tautology, but it does not differentiate this tool from siblings like ecosystem_link_debate_meeting or other linking tools beyond the resource name.

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 only usage context is 'Stage 3 helper,' which vaguely implies it belongs to a workflow stage but gives no explicit when-to-use guidance, prerequisites, or alternatives to consider. An agent must infer its place among many sibling tools.

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