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 discloses key behaviors: default COMPACT projection is trimmed (NOT missing fields), the I/O summary is excerpted due to result ceiling, windows capped at 50 rows, and sorted by timestamp descending. It adds material behavioral context beyond what the schema conveys.

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 tightly crafted, front-loaded with purpose in the first line, then organized into a compact logical flow: what's returned, default projection behavior, why (with measured evidence), and how to adjust. Every sentence earns its place; 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?

Given an output schema exists (so return values are documented there), 4 params all with 100% schema coverage, and the description thoroughly explains the projection behavior, row caps, sorting, and the tuning strategy, the description is fully complete for an agent to select and invoke this tool appropriately.

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 baseline is 3. The description adds value by clarifying the relationship between fields='compact'/'all' and the excerpt semantics, explaining that the compact window caps at 50 rows while the limit parameter defaults to 20, and noting agent_id narrows rather than widens. The interplay between limit and window cap is genuinely useful beyond 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 it 'Query Agent activity records for a team', specifying the verb (Query), resource (Agent activity records), and scope (for a team). It distinctively reports tool name, duration_ms, and I/O summary, differentiating it from siblings like task_run, agent_list, or meeting tools. Well-defined purpose.

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 documents the default compact projection, explains the reason (43.9k char transcript ceiling), and provides concrete guidance: narrow with agent_id rather than widening limit for narrower windows, and use fields='all' for full records. It tells the agent exactly when and how to adjust parameters for different needs.

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 and does an exceptional job. It discloses the compact projection is a trimmed view not missing data, explains that offline agents are terminated processes that cannot be messaged or assigned work, reveals the payload-size failure history and the 96.4% offline-row statistic, and explicitly assures nothing is deleted. This is richly transparent about edge cases and consequences.

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 a leading one-line purpose, then a compact-projection explanation, then offline-handling context. While dense and front-loaded, some sentences are long and packed with multiple clauses; the failure-history narrative, while valuable for transparency, adds verbosity. Still, 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?

This is a complex tool with 6 parameters, an output schema, no annotations, and an unusual default behavior (count+digest for offline). The description thoroughly explains the compact vs all distinction, the offline folding logic, the termination implications, the payload-size failure rationale, and the include_offline escape hatch. For a tool of this complexity, the description is remarkably 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 coverage is 100%, so the schema fully documents all 6 parameters. The description adds context beyond the schema by explaining the relationship between include_offline and offline_preview (digest vs full rows) and clarifying what the compact projection omits. However, it doesn't add per-parameter syntax or format details beyond what the schema already 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?

Clear verb+resource: 'List a team's members'. The description distinguishes compact vs full projections and explains offline member handling, which differentiates it from sibling tools like team_list, team_status, and team_briefing that operate at the team level rather than member level. However, it doesn't explicitly name the sibling it competes with, so it loses the top score.

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 to request offline history ('on request'), when to use fields='all' versus compact, and how include_offline interacts with the default count+digest behavior. It provides clear conditional context though it doesn't explicitly state when NOT to use this tool or name alternatives.

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

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

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?

No annotations are present, so the description must cover behavioral traits. It only says 'Update' (implying mutation) but lacks details on permissions, side effects, idempotency, or what happens during the 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?

The description is a single, front-loaded sentence with no extraneous words. It is as concise as possible while conveying the core 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?

While the tool is simple and has an output schema, the description lacks usage guidelines and behavioral context. It is minimally adequate but leaves gaps for an AI agent to infer best practices.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states 'Update an Agent's running status,' which is a specific verb (update) and resource (agent status). It distinguishes from sibling tools like agent_register or agent_heartbeat by focusing on status changes.

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 no guidance on when to use this tool versus alternatives, nor any prerequisites or context. It is a bare statement of function.

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

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

Annotations are absent, so the description carries full behavioral burden. It communicates what this tool does (adds to a review queue for the user) and its underlying purpose/motivation. While it doesn't explicitly state side effects like whether items are persisted long-term or how they get resolved, the 'for user review' framing and the note about decisions 'never actually received' provide meaningful behavioral context about the tool's role in the decision workflow.

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

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

The description is compact — roughly 4 sentences that each earn their place. Front-loaded with the core action ('Add a decision item'), followed by concrete use cases, then a compelling operational rationale. No wasted prose or repetition of schema content.

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

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

For a 6-parameter tool with an output schema and 100% schema coverage, the description is nearly complete. It explains the purpose, triggers, examples, and the failure mode it prevents. Minor gap: doesn't clarify the relationship between this tool and briefing_list/resolve/dismiss lifecycle, but the sibling differentiation is adequately handled through purpose and usage guidance. The description is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with all 6 parameters fully documented in the input schema itself: title, description, options, recommendation, urgency, tags. The description doesn't add parameter-specific detail beyond the schema, which is acceptable given full coverage. The baseline of 3 applies since the schema does the heavy lifting; no additional parameter nuance is provided in the description but none is strictly 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?

Description clearly states the verb+resource: 'Add a decision item to Leader Briefing for user review.' It goes beyond and specifies the exact use case (project direction, architecture, budget, allocation) and even explains why this matters — 'a decision parked in report prose is a decision the user never actually received.' This strongly distinguishes it from siblings like briefing_list, briefing_resolve, briefing_dismiss.

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 explicit when-to-use guidance ('Use when Leader encounters decisions that require user input') with concrete examples (project direction, architecture choices, budget/resource allocation). It also gives clear exclusionary framing — anything a sub-agent leaves 'for the user to decide' belongs here — and contrasts with what should NOT happen (decisions parked in report prose). This is highly actionable for an agent deciding between this and related briefing/dismiss/resolve 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 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?

No annotations are provided, so the description carries the full burden. It explains some filtering semantics but does not disclose return volume limits, pagination, ordering, whether resolved/dismissed items are summarized or detailed, or whether this is a read-only operation. Given zero annotation coverage, this is a meaningful gap for a list-type tool.

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

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

Two short paragraphs, front-loaded with purpose and default behavior, then rationale for filter design. Efficient and focused. Slightly verbose in the project_id explanation but that content earns its place given the unusual 'current' sentinel. 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?

There is an output schema present, so return format is covered. The description covers default behavior, filtering semantics, and design rationale. Minor gaps: no mention of pagination or result ordering for a list tool, and no explicit 'read-only' statement. For a filtered list tool with output schema, this is reasonably 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 adds value by explaining the default status (pending), the project_id empty-default semantics and the 'current' special value, and the tag narrowing use case. This meaningfully complements the schema's reusable intent behind default filtering behavior.

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 uses a specific verb+resource ('List Leader Briefing items') and clarifies the default behavior (shows pending items). It distinguishes itself from siblings like briefing_add/briefing_resolve/briefing_dismiss since this is the listing operation. It could mention the 'Leader' scope more explicitly but the core purpose is clear.

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 default behavior ('Default shows pending items') and gives concrete use guidance: narrowing a long decision queue by project_id and/or tag. It explains the project_id empty-default rationale (not hiding anything, pre-2026 rows unprotected). It doesn't explicitly name alternatives among siblings, but the filtering guidance is actionable and 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, and the description only states the action without disclosing behavioral traits like idempotency, authorization needs, side effects (e.g., whether the briefing is archived), or error conditions (e.g., invalid briefing_id). This is a significant gap for a mutation 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?

Extremely concise single sentence that front-loads the action and object. However, it lacks any supporting detail; it is concise but arguably under-specified. Still, it earns a 4 for no wasted 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?

With an output schema present, the description does not need to detail return values, but it still fails to explain side effects, prerequisites (e.g., user must have permission), or error handling. For a state-changing tool, this leaves significant gaps in 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% with both parameters documented sufficiently. However, the description adds no additional meaning or constraints beyond what the schema already provides, e.g., format or expected values for 'resolution' or 'briefing_id'. 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?

Clearly states it resolves a Leader Briefing item using the user's decision. The verb 'resolve' and object 'Leader Briefing item' are specific, and it distinguishes from siblings like 'briefing_dismiss' (dismiss without decision) and 'briefing_add' (add a new 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?

No guidance on when to use this tool versus alternatives such as 'briefing_dismiss' or 'briefing_list'. It does not specify prerequisites, when a resolution is appropriate, or what scenarios call for this tool instead of others.

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 usefully discloses the matching behavior and a historical bug/fix ('2026-09-08 前这里只匹配 "@"+名'), which is unusual but real behavioral context. However, it says nothing about ordering, pagination, permissions, or what happens at the limit boundary, and the changelog detail is only marginally actionable for an agent selecting the 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?

The first sentence is a clean, front-loaded purpose statement, but the remainder is a historical changelog embedded in two languages, including a parenthetical about a bug fixed before a specific date. For an agent invoking the tool, the historical rationale does not earn its place and dilutes the signal.

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 the parameter surface is small. But the description omits ordering, default sort, and how mentions are detected (substring vs token), so an agent cannot fully predict behavior. Adequate but incomplete.

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 agent_name and limit are already documented in the schema. The description adds the '@'-optional matching rule, which is already echoed in the schema, so it adds little beyond the structured field. 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 and resource: 'Get channel messages that mention a specific agent.' This clearly distinguishes it from channel_read (all messages) and channel_send. It doesn't explicitly name sibling tools, which is why it sits at 4 rather than 5.

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

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

The description explains the matching semantics (bare name vs '@name') but gives no when-to-use guidance, no mention of how it differs from channel_read or channel_unread, and no exclusions. An agent must infer that this is the mention-filtered variant of channel_read.

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, the description carries the full burden and does so: it declares read-only semantics, that no watermark row is written, that the query has no side effects, and it defines the unread predicate precisely (mention whole-value match + project membership + later than watermark; no watermark = all unread). No contradiction with any structured field.

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

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

Front-loads the result shape, then the two facts an agent most needs (safe to call, clear via channel_read_ack), then the exact unread rule. No filler sentences.

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

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

An output schema exists so return values need not be re-explained, and the description covers the remaining unknowns for a 2-param read tool: side effects, clearing path, and the counting rule. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds semantic depth by defining what `reader` participates in (mention matching) and how the unread predicate depends on it, going beyond the schema's field-level notes.

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+scope: per-channel unread counts for one reader under one project, with a parenthetical listing the three facts returned (who, how many, latest content). This is clearly distinguishable from siblings like channel_read, channel_mentions and channel_read_ack.

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

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

Explicitly routes the agent to channel_read_ack for the adjacent action of clearing unread, and clarifies that reading here will not clear anything — a real decision boundary. It stops short of saying when to prefer this over channel_mentions or channel_read, so it is clear context without full 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?

With no annotations, the description carries the full burden and does so richly: pure read, no auto-ACK, timeout does not auto-restart the wait, cancel or connection failure ends the subscription, it cannot wake an already-ended Desktop turn, and it specifies a concrete timeout budget formula plus MCP cancel 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?

Core purpose and mechanism are front-loaded in the first sentence, and subsequent sentences each carry a distinct behavioral caveat (ACK policy, timeout semantics, cancellation, timeout sizing). It is dense but every sentence is load-bearing; minor repetition in the timeout guidance.

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 an output schema exists, return values need not be explained, and the description fully covers the lifecycle of the wait (catch-up, blocking, termination conditions) and the caller-side timeout obligations necessary to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by relating timeout_seconds and io_timeout_seconds to the required MCP request timeout (> timeout_seconds + 4 * io_timeout_seconds + 5s) and describing the cancel behavior when the client times out early.

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

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

The opening sentence gives a specific verb (等待/wait) and resource (指定对端的新消息) plus the mechanism: catch-up read first, then WebSocket wait without model polling. This clearly separates it from one-shot siblings like channel_read and polling-based approaches.

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 tells the agent this is a blocking wait with no auto-ACK, implicitly steering away from channel_read_ack, and gives operational guidance about when the returned turn can continue and how to size the MCP request timeout. It stops short of explicitly naming channel_read/channel_unread as the non-blocking alternatives.

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

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

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?

No annotations provided, so description must carry full burden. Describes the debate structure but lacks details on side effects (e.g., creation of debate session, persistence), permissions, or output specifics. Output schema exists but is not elaborated in the description.

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, front-loaded with purpose, and uses bullet points for clarity. 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?

Explains the debate process but omits details like error handling, prerequisites, or result format. Given the presence of an output schema, the description is adequate but could be more thorough.

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

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

Schema coverage is 100% with adequate parameter descriptions. The description adds minimal extra context (e.g., default roles) but does not significantly enhance understanding beyond 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?

Clearly states it starts a debate-style code review for a specific file/change, detailing the 4-round structure with defined roles (advocate, critic, judge). Distinguishes from sibling 'debate_start' by specifying code review context.

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 (for code review) and the process. Does not mention when not to use or alternatives, but the context 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?

Describes the 4-round structure and roles of Advocate, Critic, and Judge in detail, providing behavioral context. However, no annotations exist, so the description carries the full burden; it does not disclose side effects, permissions, or error conditions.

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?

Highly concise, with a clear main sentence followed by structured bullet points for the rounds. Every line adds necessary information without redundancy.

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

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

For a complex tool with 5 parameters and an output schema, the description covers the process and roles adequately. No gaps remain given the schema and output schema coverage.

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 in the schema. The description adds no additional semantic information beyond the schema, meeting the baseline expectation.

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?

Clearly states 'Start a structured 4-round debate meeting between an Advocate and a Critic,' specifying the action and resource. Differentiates from siblings like 'debate_code_review' by emphasizing structure and roles.

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?

Implies use for structured debate but lacks explicit when-to-use or when-not-to-use guidance. No alternatives mentioned, leaving usage somewhat 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?

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?

No annotations exist, so description carries full burden. It discloses that it reads execution traces, compares with similar tasks, and returns suggestions. This gives good insight into internal behavior without contradicting any hidden side effects.

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 concise sentences: first states purpose, second explains method, third tells when to use. No fluff, front-loaded, 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?

Given that an output schema exists (not shown), the description adequately covers input (task_id), process (trace reading + comparison), and output (fix suggestions). It is complete for a diagnostic tool, though could mention if any prerequisites exist.

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

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

The single parameter task_id has schema description 'ID of the failed or stuck task', which is echoed in the description ('failed or stuck task'). Schema coverage is 100%, so description adds minimal extra meaning beyond confirming the task status.

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 uses a specific verb 'auto-diagnose' and resource 'task failure', clearly distinguishing it from siblings like task_execution_trace which only reads traces. It states the tool identifies failure points and suggests fixes.

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

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

Explicitly says 'Use this when a task fails or gets stuck', providing clear guidance on when to invoke. Does not explicitly mention when not to use, but context implies it is for diagnosis rather than other task operations.

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 must cover behavior. It states the state change and that the prompt won't reappear, but doesn't mention reversibility or side effects. Adequate for a simple toggle.

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?

Single sentence with clear verb-object structure. No wasted words. Front-loaded with action.

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?

Simple tool with one optional parameter and an output schema. Description sufficiently covers purpose and effect. Could mention if dismissal can be undone, but not critical.

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 already fully describes the only parameter (cwd) with default and explanation. Description does not add further meaning beyond schema, hitting 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?

Description clearly states the action: marking current cwd as dismissed for project registration. It distinguishes itself from siblings by being project-registration-specific, unlike briefing_dismiss or ecosystem_clear_manual_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?

Tool is straightforward: call to dismiss registration prompt for cwd. The phrase 'won't ask again' makes its effect clear. No explicit when-not-to-use, but simplicity implies only use when dismissal is desired.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates that the tool 'claims' a repo, implying a state change (marking it as claimed), and returns the shallow_summary. However, it does not explain side effects in detail (e.g., whether the claim is blocking, expiration, or required permissions). The return value is mentioned, but deeper behavioral traits 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 description is extremely concise: two sentences that front-load the action and follow with necessary context. Every sentence serves a purpose, no fluff. It is efficient for an AI agent to parse.

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 (not shown but indicated), the description need not detail return values beyond mentioning shallow_summary. It explains the filtering logic clearly. However, it could be improved by noting any prerequisites (e.g., worker registration) or what happens if no matching repo exists. Overall, it is fairly complete for a claim 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%, with both parameters (worker_id, min_stars) already described in the schema. The description does not add additional meaning beyond what the schema provides. According to guidelines, baseline is 3 for high coverage, and no extra parameter insight is given.

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: 'Claim the next shallow_done repo for quality review.' It specifies the action (claim), the resource (shallow_done repo), and the context (quality review). The additional details about filtering criteria differentiate it from sibling tools like ecosystem_claim_shallow, which likely handles shallow scanning claims.

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 to use the tool: when a repo is in 'shallow_done' status with no quality_score and no active claim. It gives clear context but does not explicitly state when not to use it or mention alternative tools. However, the specificity is sufficient for an agent to understand the intended scenario.

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 full burden. It discloses atomic behavior (only one worker claims) and return fields. It does not contradict any annotations (none exist). However, it omits details like authentication needs or potential side effects beyond claiming.

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 very concise, with three clear sentences. The first sentence states the core purpose, the second explains atomicity, and the third notes additional return fields. No redundant information, 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?

Given that an output schema exists, the description appropriately does not detail return values but mentions key fields. It covers the tool's behavior and usage context well. Some possible prerequisites (e.g., needing to be a registered worker) are not mentioned, but for a tool with one parameter, it is reasonably 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% for the single parameter 'worker_id', which is already described as 'Unique worker identifier string.' The tool description does not add any additional meaning or context beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description explicitly states 'Claim the next queued repo for shallow scanning (stage_status=queued).' This clearly indicates the verb 'Claim' and the resource 'repo' with context, distinguishing it from siblings like ecosystem_claim_review which likely claims for review.

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 guidance by noting atomicity (only one worker gets each row) and that since v1.7.0 it returns extra fields to avoid a separate ecosystem_repo_get call. This implies when it's beneficial to use, but lacks explicit when-not-to-use or alternatives.

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

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

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?

With no annotations, description carries full burden. Adds ordering behavior and detailed status caveat (e.g., 'running' only matches pre-v1.6.2 rows). Read-only nature implied but not explicit.

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?

Single sentence is highly concise and front-loaded with key action, ordering, and filter option. 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?

Sufficient for a simple list tool with output schema. Missing explicit read-only declaration and usage context against similar sibling tools, but otherwise 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 coverage is 100%, so baseline 3. Description adds no extra meaning beyond schema; the status filter is summarized but schema already provides detailed 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?

Clearly states it lists deep-reviews with ordering (newest-first) and optional status filter. Distinguishes from siblings 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?

No guidance on when to use this tool versus alternatives (e.g., ecosystem_deep_review_status, ecosystem_search, summary tools). Only describes basic functionality without usage context.

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

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

With no annotations provided, the description carries full burden—and it delivers richly. It discloses the async nature (queued vs running), the derived status column behavior change, the watchdog auto-fail mechanism with timeout_minutes, and the external dependency on the Leader spawning a sub-agent via CC Agent tool. This is exceptional behavioral transparency for an async mutation 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?

The description is dense but efficiently organized—one opening sentence stating the core action, followed by a detailed paragraph covering secondary behaviors. Every sentence earns its place: the queuing mechanism, status derivation, watchdog timeout, and Leader responsibility are all relevant for correct invocation. No waste 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?

This is a complex async tool with side effects, a background process, and external dependencies. The description covers all these aspects: queueing semantics, status derivation, timeout auto-fail, and the Leader/spawn dependency. The interaction between stage_status and derived status is explicitly clarified. Output schema exists, so return values don't need explanation. Completeness is high for this complexity level.

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 4 parameters. The description adds context for repo_id (target of the review) and the timeout_minutes mechanism (auto-fail), but does not add new semantic meaning for agent_id or priority beyond what the schema already states ('Optional pre-assigned agent identifier', 'medium/high/critical'). Baseline 3 is appropriate when 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 is highly specific: 'Queue a deep-review for a repo and return the dispatch prompt.' It names the exact resource (EcosystemDeepReview row queued on the funnel), the action (queue), and the return value (dispatch prompt). It clearly distinguishes from siblings like ecosystem_deep_review_status/list/cancel by being the only request/creation tool.

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

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

The description clearly explains the queueing workflow, the derived status fields, the background watchdog behavior, and the timeout handling. However, it does not explicitly state when NOT to use this tool or name an alternative (e.g., ecosystem_deep_review_request_batch for batch requests, or shallow review tools). The Leader-responsibility note gives useful context on the distributed workflow.

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?

No annotations are provided, so the description must disclose behaviors. It mentions that the diff is computed dynamically from the event log (v1.6.0 event sourcing), which implies a read-only operation and provides version context. However, it does not address potential side effects, performance implications, or data freshness guarantees, leaving some 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?

The description is three concise sentences: first states the main action, second describes the output, and third provides context (replacing legacy). Every sentence adds value with no unnecessary words, and the structure is front-loaded with the core 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 description explains the output (summary counts by event type) and differentiates from the legacy approach, which is sufficient given the existence of an output schema. However, it could mention edge cases (e.g., empty result) or performance notes, but overall it is complete enough for a diff 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% with both parameters (from_date, to_date) described in the schema as YYYY-MM-DD inclusive. The description does not add additional semantics beyond what the schema provides, so it meets the baseline without improvement.

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 that the tool returns a time-period diff computed dynamically from the event log, grouping events by type (new repos, topics, stars, status). It uses a specific verb (return) and resource (diff), and distinguishes itself from the legacy index_diff snapshot approach.

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 clear context by stating it replaces the legacy index_diff snapshot approach, implying it is the preferred method for dynamic diffs. However, it does not explicitly state when to use this tool versus other ecosystem tools like ecosystem_summary_* or ecosystem_repo_events.

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?

Discloses API endpoint, return types including success/failure cases, and that dry-run results are excluded. Additionally warns about obsolete field names and legacy API behavior. No annotations exist, so description carries full burden and meets it.

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

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

Well-structured with a brief summary, API mapping, and clear bullet points for each possible return scenario. Every sentence provides necessary information without redundancy.

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

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

Given zero parameters and a modest output schema, the description covers all needed details: endpoint, response shapes, error conditions, and the meaning of success. The presence of an output schema is complemented by the description's field explanations.

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 is empty and schema coverage is 100%, so there are no parameters to document. The description compensates by thoroughly explaining the output structure and various response shapes, adding value 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?

Clearly states it fetches the latest IndexDiff snapshot for the current project. Distinguishes from siblings like ecosystem_index_update and ecosystem_diff_period by specifying it returns the most recent diff from a real (non-dry-run) update.

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?

Implies usage for retrieving the latest diff but does not explicitly mention when not to use or provide alternative tools. The mention that dry-run previews are not persisted gives some guidance, but no direct comparison with 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?

With no annotations provided, the description carries the full burden of disclosure, and it delivers richly. It details the full pipeline, the config sources (min_stars gate, focus_topics, alert_max_new_per_scan), and explicitly states which tables are touched when dry_run=False vs. untouched when dry_run=True, citing BUG #6/#8 fix and a test name. This is exemplary transparency for a state-mutating 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 front-loaded with the core action and then provides dense technical detail. While every sentence earns its place (config, pipeline, dry_run semantics, test reference), it is fairly long and includes somewhat esoteric details like BUG #6/#8 reference numbers that a typical agent user may not need.

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

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

Despite having an output schema (which relieves the need to explain return values), the description is exceptionally complete for a complex tool with zero annotations. It explains config sources, the full pipeline order, the dry_run guardrails, which tables are written, and even provides a verification test reference. This leaves no ambiguity about 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% and the single dry_run parameter is fully described in both the schema and the description. The description reinforces the semantics ('simulate... return diff preview' vs 'persist profile upserts'). Baseline 3 is correct since the schema already documents the parameter thoroughly and the description adds only modest reinforcement.

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 ('Trigger ecosystem index update — runs scanner + computes diff') with a specific verb and resource. It distinguishes itself from siblings like ecosystem_scan by explicitly describing the full pipeline (gh search → classify → diff → alert → persist), which differentiates index_update from the raw scan 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 explains the operational context: scan config comes from project ecosystem settings, and explicitly documents the dry_run behavior (default True = simulate, False = persist). It clearly states when writes happen vs. when they don't, though it doesn't explicitly name alternative tools to use instead.

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

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

The description reveals that the tool writes 'debate_meeting_id' onto reviews, which is a behavioral trait beyond the input schema. However, with no annotations provided, it omits details like idempotency, error handling, or whether the write is destructive. The description is adequate but not 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 three sentences, each earning its place: first states the purpose, second adds usage context, third explains the effect and reason. It is front-loaded and contains zero wasted 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?

Given the existence of an output schema, the description correctly avoids explaining return values. It covers the full workflow context (the hook that uses the written data), making it self-contained for an agent to understand when and why to invoke the tool.

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

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

The input schema already provides 100% coverage with descriptions for both parameters. The description adds context by referencing the origin of the parameters (e.g., 'returned by debate_start'), but this does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'link debate_start meeting id back to review rows'. It specifies the action (link/write), the resource (review rows), and distinguishes itself as a 'Stage 2 helper' in the debate workflow, setting it apart from sibling tools like debate_start and ecosystem_trigger_debate.

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 says 'Called immediately after debate_start succeeds', providing clear when-to-use guidance. It does not explicitly exclude other contexts or mention alternatives, but the sequential dependency is well-communicated.

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 full burden is on description. It only states the action (linking) but omits behavioral traits like idempotency, overwrite behavior, permissions, or error handling. Minimal disclosure for a mutation 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?

Very concise single sentence, front-loaded with key action. However, it is extremely terse and could benefit from slight expansion without losing efficiency.

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 tool with an output schema, the description lacks context about its role in the pipeline (Stage 3), prerequisites, or outcome. Not enough for an agent to decide when to invoke it.

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

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

Schema coverage is 100%, and existing parameter descriptions are clear ('Task id returned by...', 'Target deep_review row id.'). The description adds no extra meaning, so baseline 3 is appropriate.

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

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

The description states 'link integration task id back to review row', which is a specific verb+resource that clarifies the tool's purpose. However, it does not differentiate from sibling tools like 'ecosystem_link_debate_meeting', but the action is distinct enough.

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 versus alternatives. The description mentions 'Stage 3 helper' implying a pipeline context but provides no explicit when/when-not or alternative tools.

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