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

No annotations provided, so description carries full burden. Only states it builds a packet without execution. Does not disclose whether the packet is stored, side effects, permission requirements, or what constitutes a valid packet. Minimal behavioral disclosure.

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 that is front-loaded with the core action and key differentiator. No unnecessary words, every part earns its place.

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

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

With 7 parameters, an output schema, and many related sibling tools, the description is too brief. It does not explain what a 'dispatch packet' is, how it fits into the workflow, or what the output contains. Leaves the agent needing to infer context from tool names.

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. Description does not add any parameter meaning beyond what the schema already provides. Schema descriptions are adequate, so no extra value 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 'Build an Agent Exec dispatch packet' with the specific verb 'Build' and resource 'Agent Exec dispatch packet'. The phrase 'without invoking execution' distinguishes it from sibling tools that cause execution (e.g., dispatch_handoff, chain_pm_then_agent).

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?

Implied usage as a preparatory step ('without invoking execution'), but no explicit guidance on when to use this tool vs alternatives like handoff_contract or when to avoid it. No exclusion criteria or context provided.

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 full burden. It states it is a read operation ('Read the public...'), describes what is returned, and gives an example. It does not mention side effects, but as a read-only contract query, that is acceptable. Slight deduction for not explicitly stating safety profile.

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: description, when to use, when not to use, examples. Every sentence serves a purpose with no redundancy.

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

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

Given the presence of an output schema (has output schema: true), the description does not need to detail return values. It covers purpose, usage guidelines, and provides an example, making it complete for a contract-reading 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?

Only one parameter (workspace_id) with 100% schema coverage. The description adds value by clarifying that leaving it empty uses local configuration, which goes beyond the schema's 'Optional local workspaceId' description.

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 reads the public Nogra brief contract and returns fields, markdown anchors, default return policy, etc. It distinguishes itself from siblings like brief_save and brief_validate by focusing on reading the contract before validation or save.

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 provides when to use (draft a brief from user intent, check markdown sections, confirm return policy) and when NOT to use (not execution approval, not to dispatch work alone). This helps the agent select it correctly over 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?

Discloses major behaviors: marks ready, validates, renders markdown, returns localWrites. No annotations provided, so description carries full burden; it covers the core actions but could mention idempotency or 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?

Concise, well-structured with separate sections for purpose, behavior, usage guidelines, and a clear example. 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 the tool's simplicity (2 optional params, output schema exists), the description covers purpose, parameters, behavior, and returns via example. No gaps.

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. Description adds practical guidance about when payload is required (hosted mode) and brief_id shape, raising 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 clearly states it promotes a saved public Nogra brief draft, and distinguishes from siblings like brief_save by explicitly saying not to use this for edits.

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 (convert draft, produce stable path) and when-not-to-use (hosted/plugin mode rely on local payload; not for editing) with alternative tool brief_save.

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 fallback behavior (draft JSON first, then promoted markdown) and example output shows status and path. No annotations provided, so description carries burden; it is mostly transparent but lacks explicit read-only declaration.

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 sections, examples, and clear language. Not overly verbose, but could be slightly more concise; however, 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 one parameter and an output schema, description covers purpose, usage context, fallback behavior, and example. No obvious gaps; complete for 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 coverage is 100%, so baseline is 3. Parameter description in schema already covers the brief_id purpose. Description adds minimal extra meaning 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 'Read a public Nogra brief by id' with fallback logic. Distinguishes from siblings by explicitly listing when not to use (e.g., recent_briefs, brief_validate).

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

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

Explicit 'When to use' and 'When NOT to use' sections with specific alternative tools (recent_briefs, brief_validate). Provides clear context for when this tool 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 present, so the description carries the full burden. It discloses that in hosted mode there is no persistent server-side storage and that it returns localWrites. However, it does not mention side effects, idempotency, or error behavior, which would improve transparency.

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 clear sections and an example. It is appropriately concise, though the example adds some length. 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 the tool's complexity (3 parameters, output schema present), the description explains the return value structure (localWrites, path, briefId) and the tool's role in the draft lifecycle. It could mention more about error cases or state changes, but 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 the baseline is 3. The description does not add significant semantic information beyond the schema's property descriptions; it only repeats the function of source as an optional label. The example indirectly shows usage but does not deepen parameter understanding.

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 saves a Nogra brief draft, parses input, and returns localWrites. It distinguishes from siblings like brief_promote and run/event tools, making the purpose explicit.

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

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

Provides explicit 'When to use' and 'When NOT to use' sections, including alternatives such as brief_promote and run/event tools. This gives clear guidance on when to invoke this tool versus 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 provided, so the description fully covers behavior: it does not persist, returns structured errors instead of raising, and normalizes input. The example clarifies the return shape, compensating for missing annotations.

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

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

The description is well-organized with clear sections, no wasted words, and front-loaded with the core purpose. Every sentence serves a 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?

For a validation tool with one parameter and an output schema, the description is complete. It explains the logic, error handling, and provides an example, leaving no gaps for an agent.

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 description for payload. The description adds context about parsing and normalization, but the schema already specifies types. The example provides additional clarity, warranting a score 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 clearly states the tool validates a brief payload without persisting it, using specific verbs like 'validate' and 'normalize'. It distinguishes from siblings like brief_save, brief_read, and recent_briefs.

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 provides when to use (check before save/promote, inspect normalized shape) and when NOT to use (not for persisting or reading), referencing sibling tools directly.

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 behavioral traits. It mentions persistent chain-state and single chain id but omits critical details such as destructive potential, authentication requirements, error handling, or consequences of incorrect parameters.

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 at one sentence, containing no wasted words. However, it could be slightly expanded to include structured guidance without losing brevity.

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

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

Despite the existence of an output schema and rich input parameters, the description lacks essential context about the chain lifecycle, parameter interplay, and prerequisites. This is insufficient for an agent to reliably 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?

Schema coverage is 100% with detailed descriptions for all 8 parameters. The tool description adds no additional parameter semantics beyond what is already in the schema, so a baseline score 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 the tool chains PM and Agent phases under a single chain id with persistent chain-state, distinguishing it from standalone dispatch tools. However, the terms 'PM' and 'Agent' are not explicitly defined, which may cause ambiguity for unfamiliar agents.

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 like 'dispatch_handoff' or 'agent_exec_packet'. With 29 sibling tools, the lack of usage context makes it difficult for an agent to select the correct 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?

No annotations provided, so description carries full burden. Discloses that the tool only builds a handoff, does not execute, requires a saved brief, and is for plugin-mode crossing. No contradictions.

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 main description, usage guidelines, and example. Every sentence adds value, no redundancy, front-loaded with purpose. Concisely comprehensive.

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 6 parameters, no annotations, and an output schema (example provided), the description covers when/why/how, includes an example output, and distinguishes from siblings. Missing error cases, but overall sufficient for correct invocation.

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

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

Schema description coverage is 100%, baseline 3. Description adds value by elaborating on parameter roles (e.g., 'caller-defined runtime target', 'optional linkage') and providing an example with parameter values, though schema already has decent 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 builds a public dispatch handoff, bundles a brief, target, and optional fields. It distinguishes from sibling tools by emphasizing it does not execute work and is specific to handoff preparation.

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

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

Explicit 'When to use' and 'When NOT to use' sections with bullet points. Provides clear contexts, exclusions (e.g., not for execution), and mentions alternative tool (transport_register) for brief-less tracking.

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?

Since no annotations are provided, the description carries the full burden. It discloses that the contract is ephemeral, not to be persisted, and that the Manager must not implement scope inline. It also instructs to stop and surface missing primitive instead of fallback. However, it does not cover rate limits, authentication, or side effects beyond these constraints.

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 summary, usage sections, and an example. It is somewhat verbose but every sentence serves a purpose. Minor redundancy exists (e.g., 'Manager must not implement' appears twice), but overall it is efficiently organized.

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's complexity and the presence of an output schema, the description is remarkably complete. It covers when to use, when not to use, behavioral constraints, and provides an example return format. No critical information is missing for an AI agent 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 description coverage is 100%, providing a baseline of 3. The description adds value by listing supported values for 'kind' (executor or verifier) and explicitly labeling 'role' as deprecated, which is not in the schema. The example further clarifies usage.

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 returns an ephemeral Nogra handoff contract, specifying the verb 'return' and the resource 'handoff contract'. It distinguishes the tool's purpose by explaining its role at dispatch or verification boundaries, making it stand out from siblings like brief_contract or dispatch_handoff.

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 includes explicit 'When to use' and 'When NOT to use' sections, detailing after brief approval for executor, before evidence checks for verifier, and listing prohibitions such as not calling repeatedly, not persisting the prompt, and not using it as execution approval. This provides excellent guidance on alternatives and 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?

The description clearly states that the tool does not write files and does not execute commands, and explains its server-side role. Since no annotations are provided, the description fully covers behavioral traits.

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 clear sections and examples, but it is somewhat lengthy. However, every sentence adds value, so it earns a 4.

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 2 parameters with full schema coverage and an output schema, the description is complete. It covers purpose, usage, parameters, examples, and behavioral constraints.

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 context by explaining default values and mode semantics (plugin vs standalone) with examples, but the schema already defines these well.

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 specifies the verb 'Return' and resource 'public Nogra init bundle', clearly distinguishing it from file-writing or execution tools. It explicitly states what the tool does: provide a bundle for Claude Code to write locally.

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 explicit when-to-use scenarios (initialize Nogra, respond to user requests, retrieve bundle) and when-not-to-use (not an installer, not overwrite without asking, not configure auth/run commands). It also differentiates mode=plugin vs standalone.

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 fully discloses that the tool is download-on-demand, does not write files or start processes, and that the client should only write files after user opt-in. This covers key behavioral traits beyond the schema.

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

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

The description is well-structured with a summary, behavioral notes, bullet-point usage guidelines, and an example. It is slightly verbose but every sentence adds value; 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 the tool has an output schema and 2 parameters fully documented, the description provides complete context: purpose, behavior, usage guidelines, and an example. No gaps remain for an agent to use 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 baseline is 3. The description adds meaning by giving an example feature_id ('local-pinboard-renderer') and explaining workspace_name as used for templating, which is not obvious from 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 returns an optional Nogra feature bundle for local writing after opt-in, specifying verb and resource. It distinguishes from siblings like init and registry by focusing on on-demand download of optional features.

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 when-to-use and when-not-to-use sections with two use cases (install optional feature, repair/update) and two anti-patterns (not during default init, not auto-starting processes). This is thorough guidance.

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

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

With no annotations, the description discloses the writing behavior, return fields, and lightweight nature. Could be more explicit about side effects or idempotency, but overall adequate.

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 sections and examples, but slightly verbose. Front-loaded with the core purpose. Good readability.

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 purpose, usage, parameters, return values (via example), and exclusions. Lacks error handling or rate limits, but given the presence of an output schema and completeness of other aspects, it is sufficient.

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. The description adds context about sanitization of IDs, relationship to event structure, and example usage, 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?

The description clearly states the tool appends a workspace activity event and lists the fields. It distinguishes from siblings like update_run and large reports via explicit 'When NOT to use' sections.

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

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

Explicit 'When to use' and 'When NOT to use' sections with clear conditions and alternatives (e.g., update_run for run status). Examples further illustrate appropriate usage.

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. It discloses key behaviors: it is a dry-run (no live provider call), it redacts secret-shaped text, it stores a receipt, and returns a handoff id plus guidance. While it does not mention rate limits or authentication, it adequately sets expectations for a read-like 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 concise (around 150 words) and well-structured with a clear first sentence, bullet-point sections for when to use/not use, and a concrete example. Every sentence adds value, and important information is front-loaded.

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

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

Given the tool's moderate complexity (7 optional parameters, output schema exists), the description is complete. It explains purpose, usage constraints, and key behaviors. The example illustrates typical invocation. The output schema (not shown) likely covers return values, so the description need not elaborate.

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 covers all 7 parameters with descriptions (100% coverage), so the description adds limited extra meaning. It provides an example showing typical usage of provider, prompt, context, and intent, which helps contextualize the parameters, but it does not elaborate on each parameter beyond what the schema states.

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

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

The description clearly states the tool's purpose: 'Create a dry-run provider handoff receipt.' It then details the steps (renders template, redacts secrets, stores receipt, returns id and guidance), and explicitly distinguishes it from siblings by noting it does not call a live provider, unlike related tools like dispatch_handoff or provider_handoff_read.

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 includes explicit 'When to use' and 'When NOT to use' sections, providing clear context for appropriate usage. It advises against using this tool for actual provider calls (suggesting alternative behavior) and for run tracking (pointing to event/run tools). However, it does not name specific sibling tools to use instead, which would make the guidance even stronger.

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?

Despite no annotations, the description fully discloses behavior: looks up by id, validates id shape, reads from workspace directory, returns redacted prompt and redaction labels. It also mentions that missing ids return a missing status. This covers read-only nature, failure modes, and expected outputs comprehensively.

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

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

The description is concise: a single sentence for the main action, a bulleted list for usage, and an example. Every sentence adds value, and the structure is front-loaded with the core purpose. 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?

Given the tool's simplicity and the presence of an output schema, the description covers the necessary context: lookup process, return fields (status, handoffId, renderedPromptRedacted, redactions), and error case. No gaps remain for this straightforward lookup 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 descriptions for both parameters. The description adds value beyond the schema by explaining the deprecation of consult_id, the expected shape for handoff_id, and an example usage. This extra context justifies a score above the baseline 3.

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

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

The description clearly states the tool reads a redacted rendered prompt for a stored provider handoff receipt. It specifies the verb 'read', the resource 'stored provider handoff receipt', and the outputs (redacted prompt, redaction labels). It distinguishes from sibling tools like provider_handoff (write) by focusing on inspection of existing receipts.

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 lists when to use (inspect redacted prompt, recover by id) and when NOT to use (before creating receipt, for unredacted secrets). While it does not name alternative tools directly, the context and 'when not to use' provide clear guidance. Missing explicit sibling names but still strong.

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 description explains return of draft JSON and promoted markdown briefs, and example output. Lacks discussion of permissions or side effects, but covers main behavior.

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 sections, concise, and includes an example. No superfluous 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?

Output schema exists, so return value details are covered. Description provides additional context about workspaceId and briefs in example. Single parameter is well-documented.

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?

Only one parameter (limit) with 100% schema coverage. Description adds context by showing example usage and clarifying that it returns both drafts and promoted briefs.

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?

Specifies verb 'list', resource 'recent public Nogra briefs', and differentiates from siblings like brief_read and write lifecycle 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?

Explicit 'When to use' and 'When NOT to use' sections provide clear context and mention alternatives (brief_read, write lifecycle 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 provided, so the description carries full burden for behavioral transparency. It clearly indicates read-only behavior ('Read recent...') and mentions the underlying data source ('.nogra events log'). However, it does not disclose potential limitations such as rate limits or whether events are persisted, but for a simple read tool this is acceptable. Score 4 instead of 5 due to minor omission of 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?

The description is concise and well-structured with sections for purpose, usage guidelines, and an example. Every section is informative and no unnecessary text is present.

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 only one optional parameter, an output schema (mentioned in context), and clear usage guidelines, the description fully covers what an AI agent needs to use the tool correctly. No gaps remain.

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

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

The schema has 100% coverage (limit parameter with description). The description adds an example but no additional semantic meaning beyond what the schema provides. 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 it reads recent workspace activity events, using a specific verb ('Read') and resource ('recent workspace activity events'). It distinguishes itself from sibling tools like recent_runs and post_event, making the tool's purpose unambiguous.

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

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

The description explicitly states when to use (inspect recent activity, build caller-driven views) and when NOT to use (for run status history or appending events), providing direct alternatives (recent_runs, post_event). This is excellent guidance for AI agent selection.

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?

Without annotations, the description carries full burden; it correctly implies a read operation by using 'Read' and describes the output content, though it does not explicitly state safety or auth requirements.

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

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

The description is well-structured with a clear purpose, detailed returns, usage guidance, and an example, all in a front-loaded format with no unnecessary 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?

Given the simple single-parameter tool and the presence of an output schema, the description fully covers the tool's behavior, use cases, and output, leaving no gaps.

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 explaining the returned fields and showing usage with an example, going beyond the schema's brief parameter description.

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 ('Read') and resource ('recent workspace run updates'), and clearly differentiates from siblings by noting that 'recent_events' handles event history and 'update_run' handles writes.

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

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

Explicit 'When to use' and 'When NOT to use' sections provide clear context and alternatives, such as using 'update_run' for writes and 'recent_events' for general activity 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?

With no annotations provided, the description fully bears the burden. It discloses that the tool applies a public filter, returns redacted text and category labels, and does not write or store anything. No contradictions.

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 appropriately sized with clear sections (When to use, When NOT to use, Examples). Each sentence serves a purpose, no wasted words, and the structure aids 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?

For a simple tool with one parameter and an output schema, the description is fully complete. It explains the purpose, usage context, behavioral constraints, and provides a concrete example, leaving no gaps for an AI agent.

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% for the single parameter, so baseline is 3. The description adds value by explaining the output behavior, providing context about secret-pattern filtering, and including an example, which goes beyond the schema's parameter description.

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 'Redact secret-shaped text without writing a record,' specifying the verb (redact) and resource (text). It distinguishes itself from sibling write-tools by clarifying it does not write, which differentiates it effectively.

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

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

Explicit 'When to use' and 'When NOT to use' sections provide clear guidance. It states to use for previewing secret-pattern labels before writing and for building masking logic, and warns against using it for destructive storage or provider handoff receipts.

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 behavioral disclosure responsibility. It states the tool reads a public registry and returns a payload, but does not discuss permissions, rate limits, idempotency, or any side effects. The description adds some behavioral context (the registry is public) but lacks depth.

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 distinct sections: core purpose, when to use, when not to use, and an example. It is concise (approximately 100 words) and front-loaded with the primary action. Every sentence contributes meaning without redundancy.

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

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

Given the tool has zero parameters and an output schema exists, the description thoroughly explains the return payload's composition (tool names, resource URIs, etc.) and provides a realistic example. It could mention that the registry is likely cached or that access may be restricted, but overall it is sufficiently complete for a simple read operation.

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

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

The tool has zero parameters and schema coverage is 100%, so the description does not need to explain parameters. Baseline for 0 params is 4. The description adds value by explaining what the output contains, which indirectly clarifies the tool's semantics.

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

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

The description clearly states the tool reads the public Nogra MCP V1 registry and returns specific components like tool names and resource URIs. This is a specific verb+resource combination, and the 'When to use' section helps distinguish it from sibling tools by emphasizing its role in discovery before choosing other 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 includes explicit 'When to use' and 'When NOT to use' sections, providing clear context for when the tool should be selected (to discover public registry contents) and when alternatives are better (e.g., reading resource contents directly). This directly addresses when to use it vs 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, the description carries full burden. It discloses the core behavior (abort/cancel) and mentions ledger locality in hosted mode. It does not cover auth requirements, rate limits, or potential side effects beyond localWrites. Adequate but not rich.

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

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

The description is concise: two sentences plus a line about hosted mode. It front-loads the purpose and adds necessary context without fluff. Every sentence contributes.

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's complexity (4 params, nested object, output schema exists), the description covers essential use cases and parameter guidance. It could add more about cancellation process or return behavior, but overall it is sufficient for an AI agent to select and 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%, but the description adds value by explaining current_run's purpose in hosted/plugin mode and clarifying reason as human-readable. It provides context beyond the schema's parameter descriptions, though the schema itself is already descriptive.

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 aborts or cancels a Transport run, with specific use cases: user stops executor, cancels a run, or marks a dispatched run cancelled without pretending verification completed. This verb+resource combination is distinct from siblings like transport_ack or transport_return.

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 tells when to use the tool: 'Use when the user stops an executor, cancels a run, or a dispatched run must be marked cancelled...' It also provides context for hosted/plugin mode with current_run. However, it lacks explicit when-not-to-use or alternatives, though the sibling tools imply other transport actions.

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 bears full responsibility for behavioral transparency. It only mentions basic action and two modes, but fails to disclose side effects, required permissions, or whether the action is destructive or reversible.

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

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

The description is a single, concise sentence with no waste. It is front-loaded with key action and mode distinction. Slight improvement could be structured listing of behaviors per mode.

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 the existence of an output schema, the description is too brief for a tool with two modes and optional parameters. It does not explain what 'local-ledger guidance' means or behavior when run_id is omitted.

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% (both parameters have descriptions), so the description adds no additional parameter meaning beyond the schema. Baseline of 3 is appropriate per guidelines.

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 verb 'acknowledge' and the resource 'Transport run', distinguishing it from siblings like transport_abort or transport_status. It also hints at two modes, but could be more explicit about what 'acknowledging' entails.

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 context by mentioning non-hosted and hosted modes, giving a hint about when to use. However, it does not explicitly state when not to use this tool or suggest alternatives among the many transport-related 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?

The description discloses mode-dependent behavior (hosted mode returns guidance, not cleanup) and that parameters are only for non-hosted mode (via schema). However, it lacks details on destructive scope, permissions required, or side effects beyond the schema, especially since no annotations are provided.

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 clearly conveys the tool's primary action and the hosted mode behavior. Every word earns its place, and it is appropriately front-loaded.

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

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

Given the presence of an output schema, the description need not explain return values. It covers both modes and parameter applicability. However, it does not address edge cases like calling with parameters in hosted mode or prerequisites for cleanup, which would improve completeness.

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

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

Schema coverage is 100% with good descriptions. The description adds critical context by linking all parameters to 'Non-hosted only' mode, clarifying that they are ignored in hosted mode. This adds value 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 action ('clean') and the resource ('non-hosted Transport state'), and distinguishes between non-hosted and hosted modes. However, it does not differentiate from sibling tools like transport_abort or transport_return, leaving room for ambiguity.

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

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

The description implies usage contexts (non-hosted vs hosted) but provides no explicit guidance on when to use this tool versus alternatives like transport_abort, transport_return, or transport_status. No exclusions or when-not-to-use guidance.

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

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

No annotations provided; description does not disclose side effects, mutability, permissions, rate limits, or any behavioral traits beyond the single action line. The parameter descriptions hint at behavior, but the main description is wholly insufficient.

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

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

The description is concise in word count but under-specified for the complexity of the tool (15 parameters, no annotations). It lacks essential context, making it inadequate rather than efficiently lean.

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 high parameter count and no annotations or output schema visible, the description is a single sentence with no elaboration on behavior, use cases, or expected outcomes. It is far from 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%, and parameter descriptions are detailed, so the description need not add additional meaning. Baseline 3 applies; description does not enhance 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?

Description states 'dispatch a workflow target through Nogra Transport', which is a clear verb and resource, but does not differentiate from many sibling tools like transport_register or transport_update, leaving ambiguity about exactly what 'dispatch' entails.

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 vs alternatives, no prerequisites or exclusions. With 30+ sibling tools, the lack of usage context is a significant gap.

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

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

Missing annotations, so description must disclose behaviors. It indicates a read operation but does not confirm safety, permissions, or side effects. The 'hosted mode returns local-ledger guidance' is vague.

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, no wasted words. Front-loaded with key action. However, could benefit from slightly more detail without losing conciseness.

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, the description is too brief to fully contextualize the tool's behavior across modes, leaving ambiguities about what 'events' and 'guidance' entail.

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. Description adds minimal context for 'run_id' about hosted mode, but mostly repeats schema info. No significant added value.

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 verb 'Read' and the resource 'Transport events', distinguishing between non-hosted and hosted modes. However, it does not differentiate from sibling tools like 'recent_events' or 'transport_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 explicit guidance on when to use this tool vs alternatives. The description implies it is for reading events, but lacks context on when to prefer it over similar tools like 'recent_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?

No annotations are provided, so the description carries full burden. It transparently describes all side effects: creates state-only record, allocates paths, persists atomically, appends event. It also clarifies that it does not execute work.

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 clear sections, no unnecessary words, and an illustrative example. 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 the tool has an output schema (implied), 3 parameters, and an output schema, the description covers purpose, usage, exclusions, and example. No significant gaps for a registration 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 the baseline is 3. The description adds value through an example showing typical usage of target and brief_id, and the metadata parameter is mentioned. It provides context beyond the 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?

The description clearly states it registers a public transport run with specific actions (state-only record, artifact paths, atomic persistence). It distinguishes from siblings by explicitly saying not to use for work execution or lightweight logging, and points to post_event as an alternative.

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 'When to use' and 'When NOT to use' sections, including alternative tools. This gives clear guidance on appropriate scenarios.

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. It discloses the mode-dependent behavior difference but does not explain side effects, permissions, error handling, or what 'local-ledger guidance' means. The output schema exists but is not referenced; the description is moderately transparent but lacks depth.

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 with no extraneous words. It front-loads the main action and mode distinction, making it efficient for quick scanning. Every word 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 the output schema exists, the description does not need to detail return values. However, the context of many sibling tools and the complexity of transport workflows suggests more information about preconditions, errors, or mode triggers would be beneficial. The description is minimally complete but could be improved.

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

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

Schema coverage is 100%, so both parameters have descriptions. The tool's description reiterates the schema's point for include_text and adds a mention of modes for run_id, but does not provide additional meaning beyond what 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?

The description clearly states the tool returns a non-hosted report/output payload and provides a mode distinction (hosted vs non-hosted). However, the terms 'non-hosted' and 'local-ledger guidance' may be unclear without additional context, and the purpose could be more explicit in distinguishing from 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?

The description mentions two modes but does not provide guidance on when to use this tool versus alternatives like transport_abort or transport_submit_report. No explicit when-to-use or when-not-to-use instructions are given, leaving the agent to infer context from the mode distinction.

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 two different behaviors (non-hosted vs hosted) but omits details about side effects, authentication needs, or what 'local-ledger guidance' entails. Without annotations, more transparency would be beneficial.

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 that front-loads the main purpose. No wasteful content, though it could be slightly more informative.

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

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

With 25 sibling tools, the description lacks context to differentiate usage. Output schema exists, reducing need for return-value details, but the description does not address error cases or permissions.

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 already describes all parameters clearly. The description adds minimal additional meaning beyond what the schema provides, so a baseline score 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?

Clearly states it reads Transport run state and distinguishes non-hosted vs hosted modes. However, it does not differentiate from similar sibling tools like transport_events or transport_abort.

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. The description gives context about modes but lacks indications for exclusion or prerequisites.

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 discloses the mode-dependent behavior (hosted returns guidance), but omits important details like side effects (e.g., file writes, permissions required, whether data is persisted). 'Submit' implies mutation but the safety profile is unclear.

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

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

The description is a single sentence of 18 words, efficiently front-loading the action and mode distinction. Every token adds value, with no redundancy or filler.

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

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

Despite having 7 parameters and mode-dependent behavior, the description is brief and lacks explanation of return values (though output schema exists) and selection criteria between modes. It does not help the agent understand complex interactions, leaving gaps.

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 each parameter. The tool description does not add parameter-level meaning beyond what the schema provides (e.g., mode-specific behavior is already in the schema's parameter descriptions). 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 action ('Submit a Transport report') and distinguishes the tool by specifying mode-dependent behavior (non-hosted vs hosted mode). This differentiates it from sibling tools like transport_validate_completion or transport_return.

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 does not provide guidance on when to use this tool versus alternatives. It mentions two modes but fails to explain scenarios where each mode is appropriate, nor does it list sibling tools as alternatives.

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

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

With no annotations, the description carries full burden. It discloses that the tool performs partial updates and appends an event with changed fields, indicating mutation. However, it does not mention idempotency, error handling (e.g., missing run), or authorization requirements, which would strengthen clarity.

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

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

The description is concise and well-structured: a one-line summary, bulleted when-to/when-not guidelines, and an example. Every sentence is informative with 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?

The description adequately covers purpose, usage, and examples. It mentions updating an 'existing run' but could be more explicit about the need for a valid run_id. Since output schema exists, return value explanation is not required. Overall, it is fairly complete for the tool's 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?

All six parameters have full schema descriptions (100% coverage). The description adds value by clarifying 'partial updates' and listing the updatable fields (status, phase, notes, error, summary) in context, plus a concrete example demonstrating usage with status='running'.

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 updates a public transport run with specific fields (status, phase, notes, error, summary) and appends an event. It explicitly distinguishes from transport_submit_report for writing report artifacts, differentiating it from a sibling 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 includes explicit 'When to use' and 'When NOT to use' sections, listing valid scenarios (e.g., moving run to a new lifecycle state, attaching status notes) and excluding report writing and brief draft changes, with a direct alternative (transport_submit_report).

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 description is the sole source. It does not disclose side effects, prerequisites, or whether the action is read-only or mutating. The name suggests validation without changes, but this is 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?

The description is a single concise sentence, but it is too brief for a tool with two parameters and validation logic. It could include more without being overly verbose.

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 omits what constitutes successful validation, the output format (though output schema exists), and how to interpret results. For a validation tool, this leaves significant gaps for the agent.

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 description does not add meaning beyond existing parameter descriptions. The mention of 'inline hosted evidence or non-hosted runtime records' echoes the evidence parameter but adds no new details.

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 validates completion, specifying two modes: inline hosted evidence or non-hosted runtime records. It distinguishes from siblings like transport_submit_report and transport_ack, but does not explicitly differentiate from all 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 explicit guidance on when to use this tool versus alternatives. The description implies usage after target exit, but lacks when-not conditions or references to sibling tools.

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

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

With no annotations, the description carries full burden. It reveals two modes (hosted vs non-hosted) and mentions a timeout via wait_seconds, but does not explain blocking behavior, return values, or what 'local-ledger guidance' entails. Partial disclosure but lacks key behavioral details.

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, lean and to the point. It could be more informative, but it is not verbose or cluttered. Appropriate length for a simple tool.

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

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

Despite high schema coverage and existence of an output schema, the description leaves critical gaps: what does 'returnable status' mean, what does the tool return in non-hosted mode, and how does it interact with sibling tools? The description is too sparse to fully understand usage context.

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 tool description largely repeats the schema descriptions for run_id and wait_seconds without adding new insight. No additional semantic context beyond what the schema already provides.

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

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

The description states it waits for a non-hosted Transport run, and notes a different behavior for hosted mode. It clearly identifies the resource (Transport run) and the action (wait), but does not explicitly differentiate from siblings like transport_status or transport_abort.

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 transport_status or transport_abort. The description implies it is for non-hosted runs but does not state when not to use it or suggest other 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 provided, so description carries full burden. Discloses it writes one JSONL entry to workspace directory, sanitizes run_id/brief_id, returns URI. Could mention idempotency or auth but covers core behavior adequately.

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 sections and example; no wasted sentences. Could be slightly tighter but overall efficient and readable.

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 output schema exists, description covers purpose, usage, behavior, and includes an actionable example. No obvious gaps for an append-only run status update 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% but description adds critical context: run_id is sanitized and used as filename, blank status stored as 'updated', optional brief_id and notes with sanitization. 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?

Starts with 'Append a workspace run status update'—specific verb and resource. Explicitly distinguishes from sibling 'post_event' by stating when not to use it for general activity notes.

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

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

Provides clear 'When to use' and 'When NOT to use' sections, including explicit alternatives like post_event for general notes and not for dispatching work or submitting report artifacts.

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