Bilg

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

With no annotations, the description carries the full behavioral burden. It adds a meaningful permission-related nuance ('Commenting on anyone's item is fine — unlike assignment'), but it does not disclose other behavioral details such as whether the comment is appended to a thread, whether notifications are sent, or whether the operation is reversible. For a simple mutation tool this is acceptable 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?

Three sentences with no filler: the first states the action and target format, the second clarifies permission scope, and the third gives routing guidance. It is front-loaded and every sentence earns its place.

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

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

For a simple two-parameter tool with 100% schema coverage, the description covers what the target is, how it is identified, who is allowed to use it, and when to prefer an alternative. The only minor gap is that it does not explicitly mention that existing comments can be modified via update_comment, but that is not necessary for invoking this tool 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%, so the schema already documents both parameters fully. The description repeats the target key format and item types but adds no new parameter-level meaning beyond the schema, so the 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 uses a specific verb-resource pairing: 'Add a comment to an epic, task or question' and identifies the exact key format. It distinguishes itself from create_open_question by contrasting commenting with asking a question, and it is clearly distinct from update_comment by focusing on addition rather than modification.

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 when to use an alternative: 'Use a question (create_open_question) instead when you need an answer before the work can finish.' It also clarifies that commenting on anyone's item is allowed, unlike assignment, giving the agent a clear green light without needing to infer permissions.

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 behavioral burden. It does disclose that the operation appends to the end of an existing document, implying existing content is preserved, but it omits behavior for nonexistent documents, whether changeNote is stored, and what the return/confirmation looks like. The schema mentions the blank-line separator, not 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?

Two short sentences with no filler. The core operation is front-loaded, and the second sentence adds a concrete use case rather than restating the schema.

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

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

The tool is simple and the description captures its primary behavior, but with no output schema, no annotations, and a mostly undocumented schema, the agent still lacks return/error behavior and changeNote semantics. The required parameters and use cases are at least inferable, making the definition minimally workable.

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 of the three properties (content) has a schema description, so the description must compensate for documentId and changeNote; it does neither. ChangeNote's meaning and format and documentId's identification role remain undocumented from both description and 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 uses the specific verb 'Append', identifies the resource ('existing text document'), and specifies position ('end'), so an agent can distinguish it from create_document and update_document. It stops short of explicitly naming a sibling for replace-style edits, but the operation is 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 sentence 'Useful for ongoing notes, decision logs' gives explicit intended contexts for the tool. It does not state when not to use it or name alternatives like update_document, but the guidance is clear for common append 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses a genuinely non-obvious behavior: the projectName resolution logic that prefers a VSCode workspace config file over the API key's default project. This is valuable context an agent would not otherwise know. It stops short of describing the success return value or side effects, but for a create tool the mutation behavior is largely implied.

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

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

Two sentences with no wasted words. The core purpose is front-loaded in the first sentence, and the second adds the non-obvious projectName behavior. Every clause earns its place.

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

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

For a 4-parameter tool with no annotations and no output schema, the description covers the essential behaviors: what it records, the epic linking option, and the projectName resolution rule. The main gap is that it doesn't state what the tool returns on success or how errors surface, but for a create operation this is a minor omission given the schema already documents two parameters.

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 50% (title and rationale are documented; epicId and projectName are not). The description compensates by clarifying that `epicId` links the decision to an epic and explaining the `projectName` preference logic, which goes beyond the bare schema. This adds real meaning to the two undocumented parameters, though epicId's value format is not specified.

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

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

The description opens with a specific verb and resource ('Record a decision in the project's decision log'), which clearly states what the tool does. The mention of optionally linking to an epic via `epicId` further distinguishes it from sibling create_* tools like create_task or create_epic. An agent can immediately tell this is for logging decisions.

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 tool's purpose implies when to use it (record a decision), but the description provides no explicit guidance on when to choose it over siblings like create_open_question or list_decisions. The projectName preference logic is a parameter-level guideline, not tool-selection guidance. The context for how projectName is resolved is useful, but exclusions or alternatives are not mentioned.

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 of behavioral disclosure. It adds useful behavior: binary files are not supported here, and projectName can be overridden by a workspace config. However, it does not disclose side effects such as overwrite behavior, permission requirements, or what the tool returns on success.

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 with no filler; the main purpose is front-loaded and the boundary condition is stated immediately. Every clause 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?

The description is adequate for a basic invocation with required fields and adds valuable projectName precedence context. However, with no output schema and no annotations, it leaves gaps around tags/title semantics, expected return value, and behavior when the target fileName already exists.

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 67%, so the baseline is roughly 3. The description adds meaning to content by specifying markdown/plain text and clarifies projectName resolution via the VSCode config file. Tags and title are left semantically undocumented, so the description only partially compensates for the schema gaps.

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 ('Create') and resource ('a new text document'), and pins down the format as markdown or plain text. It does not explicitly contrast with sibling creation tools like create_decision or create_task, which leaves some ambiguity about when to pick this tool over 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?

The description gives a concrete exclusion: binary files such as PDF and DOCX should be handled through the web UI. It also provides a conditional rule for preferring the VSCode workspace projectName, which is useful context for invocation. It stops short of explaining when to use this instead of sibling creation 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 provided, the description carries full behavioral disclosure. It states default values for progressStatus and planStatus, forbids deployed/done on create, explains that 'deployed' is not available to agents and must be set by a human, and describes projectName resolution from the workspace config. This is substantial and goes well beyond a basic 'creates an epic' statement.

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 every sentence earns its place: purpose, defaults, restrictions, config precedence, and workflow guidance. Important constraints are front-loaded and there is no filler 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 an 8-parameter create tool with no annotations and no output schema, the description covers the key invocation decisions: defaults, unsupported statuses, project selection, and summary-versus-document content split. It leaves some minor gaps, such as the effect of the active parameter and any success/return behavior, but an agent has enough to call it correctly in most situations.

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 only 38%, so the description must compensate, and it does. It explains the meaningful defaults for progressStatus and planStatus, the projectName config fallback, and distinguishes the summary field from documentId-linked detail. It does not clarify every parameter (e.g., active), but it adds substantial meaning to the most consequential ones.

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

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

The description opens with 'Create an epic', a specific verb plus resource, and then differentiates creation from later state changes by noting that 'deployed'/'done' are not allowed on create. It clearly identifies what the tool does and is distinguishable from siblings like update_epic, get_epic, and list_epics.

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 contextual guidance: create before non-trivial work, keep summaries in the description, and link supporting detail via documentId. It also gives an environment-based rule about preferring the VSCode workspace projectName. It stops short of explicitly naming alternatives like update_epic for later status changes, so it has clear context but not fully explicit exclusions.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It says the tool 'records' an open question, but does not mention persistence, side effects, permissions, what happens if both or neither epic identifier is provided, or what the tool returns. This is thin 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 two sentences with no filler. The core action and purpose are front-loaded, followed immediately by the parameter-selection hint. 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?

The description covers the tool's purpose, the identifier alternatives, and the nature of the question parameter, so an agent can likely invoke it correctly. However, with no annotations and no output schema, it leaves important gaps: what happens when neither or both identifiers are supplied, and what the created open question record looks like.

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 only 50% because epicId and epicKey have no descriptions in the schema. The description compensates by stating that the two are alternatives, clarifying that epicId is a UUID and giving a concrete short-key example like 'BLG-E15'. This adds meaningful guidance 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 opens with a specific verb and object: 'Record an open question under an epic.' It then defines what open questions are ('unresolved decisions or unknowns that need follow-up'), which distinguishes this from sibling tools like create_decision and create_task without needing to inspect 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?

The description gives clear context for when an open question is appropriate and instructs the agent to attach it to an epic via either epicId or epicKey. It does not explicitly name alternatives or state when not to use this tool, so it stops short of the top tier.

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 zero annotations, the description carries the full burden and delivers: status defaults to 'open', the non-obvious side effect that adding an open task to a finished epic reverts it to 'designed', the VSCode config-file override for projectName, and the semantic rule that descriptions are summaries. This discloses exactly the behaviors an agent cannot infer from the schema.

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

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

Roughly 150 words for a 13-parameter tool, and every sentence carries a distinct operational rule — no filler. The only deduction is structural: it is a single dense wall of text; short bullets or paragraph breaks would make the ~10 distinct instructions more scan-friendly for an agent, though nothing is redundant.

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

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

For a complex 13-param mutation with no annotations and no output schema, the description covers the action, defaults, edge-case state transitions, prohibitions, config override, linking strategy, and policy constraints — remarkably complete. The only gap is return-value expectations (e.g., does it echo the created task or its ID?), which would matter since no output schema exists.

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 only 46%, and the description compensates strongly: epicId gains omit-vs-provide semantics, status gains its default, projectName gains the config-file precedence rule, blockedReason gains a conditional requirement, priority gains 'leave unset if unknown', description gains 'summaries only', and documentId gains a spec-linking strategy. Seven of thirteen parameters receive meaning beyond the schema, well exceeding what a 3-point baseline would allow.

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?

Opens with a specific verb+resource ('Create a task') and immediately differentiates within a crowded create_* family (create_epic, create_document, create_decision) plus roster of task siblings (add_task_comment, update_task, list_tasks). Subsequent sentences clarify that it creates real tasks with epic linkage and status handling, so an agent cannot confuse it with create_epic or create_document.

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?

Exceptional routing guidance: 'omit for a standalone task', explicit exclusions ('Never create tasks for deploying/rolling out or for an acceptance checklist'), explicit redirection to alternatives ('use a standalone task or a new epic instead', 'create a document and link it with documentId'), and a pointer to a sibling for scope validation ('see list_tasks assignee="me"'). Also conditions the blocked status on providing blockedReason.

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 soft-delete nature, the 30-day hard-delete policy, and the restoration path (web UI only). This is valuable behavioral context beyond what the schema shows. It doesn't mention permissions or side effects, but covers the core behavior well.

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

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

Three short sentences, front-loaded with the key action. Every sentence earns its place—no filler or repetition. Structure is clear and scannable.

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 no output schema, the description covers the essential behavioral aspects: soft delete, retention period, and restoration route. It doesn't specify the return value or error handling, but those are less critical given the simplicity. Missing return info is minor.

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 0%, so the description must compensate. It provides zero additional clarification about documentId beyond the name. The agent is left to infer it's a document identifier, which is trivial but still undocumented in the schema itself. A brief note that it's the ID from list_documents or get_document would add 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 'Soft-delete' and the resource 'document', distinguishing it from update/get operations. It also adds a critical nuance (soft vs hard delete) that differentiates it from a simple 'delete'.

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 it doesn't explicitly name alternatives or when-not-to-use, the soft-delete semantics imply this is the non-destructive choice. The mention of restoration via web UI within 30 days gives practical context about the intended use case. It could be more explicit about picking this over a hypothetical permanent delete 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. It discloses that this tool creates and links back to a handoff, and it surfaces a meaningful prerequisite for open questions (epic linkage). However, it does not disclose what happens if both `handoffId` and `key` are provided, how errors are surfaced, or what the created object looks like in response.

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 sentences, all information-dense and front-loaded. The core action comes first, followed by the most important conditional constraintchers, then the input-parameter rule. No filler 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 create-style tool with no annotations, no output schema, and 5 parameters, the description provides the central usage and constraint but leaves gaps: no mention of return value, error behavior, or what happens to the handoff after derivation. It is usable but not fully self-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 description coverage is only 20%, so the description must compensate. It does so by explaining the key parameter relationship ('Provide either `handoffId` or `key`') and by tying the `type` parameter to the two creation modes. It does not explain `title` and `description`, though those are reasonably inferable from the schema and the creation context.

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 ('Create') and resource ('a task or open question from a handoff'), immediately distinguishing this from sibling tools like create_task and create_open_question by adding the handoff context and the 'linked back' behavior. It clearly states the two possible result types.

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 conveys when to use this tool: when you have a handoff (identified by `handoffId` or `key`) and want to derive a linked task or open question. It also gives an important conditional guideline: open questions require the handoff/task to be linked to an epic, while tasks do not. It does not explicitly name sibling alternatives or say 'use create_task for non-handoff tasks,' but the context is clear 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?

With no annotations, the description carries the full burden. It discloses the read-like behavior and the workspace config precedence, which is useful. However, it does not mention failure modes for missing/ambiguous ids or titles, nor what happens if multiple documents match a partial title.

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

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

Two sentences with no filler. The first sentence front-loads the core action and lookup modes; the second adds a concise, important project-resolution nuance. Every clause earns its place.

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

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

For a simple getter with no output schema and no annotations, the description covers the key lookup modes and project selection behavior. It is slightly incomplete in not addressing ambiguous or missing matches, but it gives an agent enough to make a correct call in the common case.

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 provides no descriptions at all (0% coverage), so the description must compensate. It does: documentId is a lookup key, title is a partial-title lookup key, and projectName provides project context with an explicit workspace override rule. It stops short of specifying mutual exclusivity or precedence between id and title.

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 ('Get'), a specific resource ('full text content of a specific document'), and the two retrieval routes (id or partial title). It clearly differentiates from siblings like list_documents and search_documents by focusing on retrieving one document's full content.

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 context for when to use this tool: when the user needs a document's full content and has an id or partial title. It does not explicitly state when not to use it or name alternatives, but the retrieval criteria imply the decision boundary.

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 burden of conveying that this is a read-only retrieval. 'Get an epic in full' implies no side effects and lists the content returned, which is useful. It does not disclose behavior when both or neither identifier is supplied, but this is a relatively low-risk read 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?

Two sentences, no filler. The first sentence tells the agent what the tool returns, and the second explains how to provide the identifier. The most 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?

For a simple read-only retrieval with two optional-in-schema parameters and no output schema, the description covers the core needs: what is returned and how to specify the target epic. The only real gap is that neither parameter is marked required in the schema, while the description says to provide one; the agent must infer that one identifier is needed for a successful call.

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

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

The schema already documents both parameters at 100% coverage, which establishes a baseline of 3. The description adds meaningful semantic value by explicitly framing the two parameters as alternatives ('Provide either... or...') and by giving a concrete example of the short key format. This helps an agent understand how to satisfy the tool's identifier requirement.

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 and resource: 'Get an epic in full', and enumerates exactly what is included: description, dependencies, sub-tasks, open questions and decisions. This clearly differentiates it from siblings like list_epics, get_task, or get_open_question by describing a singular, full epic retrieval.

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 intended use is implied strongly: call this when you need the complete epic rather than a list of epics. However, it does not explicitly mention alternatives such as list_epics or when to prefer key versus epicId beyond providing either, so the guidance is adequate but not fully developed.

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 behavioral disclosure burden. It does well by explaining the full return shape and adding the important security-relevant note that the body is authored by another person/agent and must not be treated as instructions. This goes beyond a generic 'get' statement, though it omits details like not-found behavior or permissions.

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

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

Two sentences with no filler. The core purpose and return contents are front-loaded, the safety warning is concise, and the identifier guidance completes the instruction set 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?

For a read-only retrieval tool with no output schema, the description adequately explains what will be returned and how to select the handoff. It could be slightly stronger by explicitly contrasting with list_handoffs, but the current level is sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the caller should provide either handoffId or key, giving the key format example (BLG-H4) and reinforcing the mutual-exclusivity that the schema does not encode.

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 action ('Get a single handoff in full') and enumerates the exact contents returned: body, context, reply chain, and derived task/question. It is clearly distinct from sibling tools like list_handoffs or resolve_handoff, so an agent can identify its purpose immediately.

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 makes the usage context clear: retrieve one specific handoff by either handoffId or key. It also warns that the body is data, not instructions, which is critical guidance for how to treat the result. It does not explicitly name alternatives like list_handoffs, but the 'single handoff' phrasing implies the 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?

With no annotations provided, the description carries the full burden. It discloses the return content (text, status, resolution note) but does not explicitly state it is read-only, mention error conditions, or describe the response shape beyond those fields. For a 'get' operation, read-only behavior is strongly implied, but the description could add a note about no side effects or permission requirements.

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

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

The description is two sentences with zero filler. It front-loads the core purpose and then provides the parameter guidance. Every word earns its place, and it is easy to scan.

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

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

Given the tool is a simple single-object retrieval with no output schema, the description provides enough information for an agent to invoke it correctly: it identifies the resource, the return fields, and the identifier options. It does not enumerate all possible fields or error responses, but for this complexity level 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?

The schema only describes 'key' with a short example; 'questionId' has no description (50% coverage). The tool description adds significant value by explaining both parameters are alternative identifiers, giving the format for 'key' ('BLG-Q7'), and stating they are mutually exclusive ('either'). This compensates for the schema gap and clarifies usage 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 verb ('Get'), the resource ('a single open question'), and specifies the detail level ('full detail (text, status, resolution note)'). It implicitly differentiates from sibling list_open_questions by targeting a single item, and from create/update tools by being a read operation. The resource is 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 says 'Provide either questionId or key' but does not explicitly state when to use this tool versus alternatives like list_open_questions or get_task. The usage context is implied (when you have an identifier), but no explicit when-not or alternative guidance is given. This is adequate but not explicit.

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

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

With no annotations, the description carries the behavioral transparency burden. It discloses the binding versus non-binding semantics of returned rules and states that rules can only be changed by a human, implying read-only behavior and authority boundaries.

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, front-loaded with the core action, and every sentence adds useful information about scope or binding semantics. 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?

For a simple read tool with one optional parameter and no output schema, the description sufficiently explains what the tool returns and how to interpret it. It does not describe return formatting, but that is not essential 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% for the single optional parameter, so the schema already documents projectName and its default behavior. The description adds no additional parameter semantics, matching the baseline for high schema coverage.

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 ('standing agent rules a project's humans have set'), which clearly identifies the tool's function. It is also distinguishable from sibling get/list tools because no other sibling targets project rules.

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 makes the context of use clear: an agent should call this to discover the project rules that its user has set. It does not explicitly name alternatives or exclusions, but no sibling tool overlaps with this function, so the guidance is adequate.

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. It adds useful behavioral detail beyond the schema by stating that taskId is a UUID, key is a short identifier like BLG-T42, and the caller should provide either one. It does not describe behavior when both arguments are supplied or error/not-found behavior, but 'Get' clearly implies a safe read 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 short sentences with no filler. The primary purpose is front-loaded, and the parameter guidance is immediately actionable. Every sentence earns its place.

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

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

For a simple single-task retrieval tool with two parameters and no output schema, the description covers the essential invocation details: the target resource and the two identifier options. It leaves minor ambiguity around combined inputs and result content, but an agent can likely call it correctly with the information given.

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 only describes 'key' and leaves taskId undocumented, while schema coverage is 50%. The description compensates by clarifying that taskId is a UUID and key is a short key format, and by indicating that the two are alternative identifiers. This adds meaningful invocation guidance beyond the raw 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 uses a specific verb ('Get') and a clear resource ('a single task'), and the 'single' qualifier distinguishes it from sibling tools like list_tasks and other task operations. An agent can immediately identify what this tool does and when to reach for it.

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 intended use is implied: retrieve one task by taskId or key. However, there is no explicit comparison to alternatives such as list_tasks or update_task, and no statement of when not to use this tool. The context is clear but not fully articulated.

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 disclosure burden, and it does so meaningfully: it discloses the newest-first ordering and the precedence rule for resolving projectName. It doesn't state read-only semantics, errors, or pagination, but for a simple list tool the most important 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?

The description is two sentences with no filler; the main action and ordering are front-loaded, and the additional config-precedence detail earns its place. It is appropriately sized for the tool's simplicity.

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

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

For a list tool with one optional parameter and no annotations or output schema, the description covers the key aspects: what is listed, ordering, and project resolution. It omits return format and pagination, but those are less critical for such a simple 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 input schema provides no parameter descriptions (0% coverage), so the description must compensate. It explains that projectName refers to a project and adds a specific precedence rule involving a workspace config file, which is genuine value beyond the bare schema. It could be more explicit about whether projectName is required, but there is only one optional parameter.

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

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

The description clearly specifies a concrete action and resource: 'List the decision log of a project' with ordering 'newest first'. This distinguishes it from sibling tools like create_decision and other list_* operations, though it doesn't explicitly name or contrast 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 gives useful context about project selection (preferring a workspace config's projectName over the API key's default), but it doesn't explicitly state when to use this tool versus alternatives or when not to use it. The use case is largely implied by the name and first sentence.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a meaningful behavioral nuance about project resolution from a local bilg.config.json. It does not explicitly state that this is a read-only operation, return shape, or pagination behavior, but 'List' implies a non-mutating query.

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

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

Two sentences, front-loaded with the core purpose and followed by a single relevant configuration nuance. There is no redundant or filler 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?

The description is adequate for a basic list operation, covering purpose and the key projectName behavior. However, with no output schema, no annotations, and zero schema descriptions, the agent still lacks clarity on return format, pagination, sorting, and limit semantics.

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 0%, so the description needed to compensate by explaining the parameters. It covers tags and projectName and hints at pathPrefix with 'folder', but it never explains limit or the exact pathPrefix-to-folder mapping. Parameter names help, but the compensation is incomplete.

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 action ('List documents in a project') and the resource, with optional filters by folder or tags. It is clear about what the tool returns but does not explicitly distinguish itself from the sibling search_documents or get_document, so it misses 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 implies this is the tool to use for listing documents and gives a useful rule about preferring a VSCode config's projectName. However, it never says when to prefer search_documents or get_document, nor does it provide any explicit 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 are provided, so the description carries the burden of behavioral disclosure. It reveals what each epic shows, the conditional acceptance stage, ordering, and workspace-specific project resolution. It does not specify pagination, exact sort order, or error cases, but for a read-only listing tool this is substantive.

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 ordering, then gives return-field detail, then the conditional config rule. It is efficiently written, though the enumerated stage list adds length; it is still justified because it clarifies edge-case behavior.

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 one-parameter tool with no output schema, the description covers the essential return content, ordering, and default project resolution. It omits exact ordering criteria and pagination, but these gaps are unlikely to block correct invocation. Overall it is adequate and above average.

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 goes beyond the schema by explaining that a VSCode workspace config's projectName takes precedence over the API key's default project, which materially affects how projectName resolves.

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

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

States a specific verb and resource: 'List epics of a project, in order.' It also clarifies scope by describing the fields shown (progress, plan horizon, active status), which helps distinguish this from singular tools like get_epic and sibling list tools like list_tasks or list_decisions.

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 use whenever epics of a project are needed, but it does not explicitly contrast this tool with get_epic for a single epic or with other list tools. It does provide one concrete usage context—preferring a workspace config's projectName—but lacks when-not or alternative-tool 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 carries the full behavioral disclosure burden. It does reveal an important behavior: prefer the VSCode workspace config's projectName over the API key default. However, it does not describe return output, pagination, or any side effects, so coverage is adequate but not rich.

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

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

The description is two sentences with no filler. The core action is front-loaded, the use case is stated immediately, and the config nuance is compactly placed at the end. Every sentence earns its place.

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

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

For a simple two-optional-parameter list tool, the description covers purpose, usage context, and the key projectName nuance. It does not explicitly say when not to use it or describe the return shape, but with no output schema and clear naming, the missing pieces are minor rather than 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 coverage is 100%, so the baseline is 3. The description adds extra meaning for projectName by specifying the config-file precedence rule, which goes beyond the schema's 'Defaults to the API key's default project' and adds real selection guidance.

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

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

The description uses a specific verb and resource: 'List folders within a project.' It clearly identifies what the tool does and is distinct from sibling list tools by the folder resource, though it does not explicitly name or contrast any sibling.

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

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

The phrase 'Useful for browsing the structure before searching' provides a clear usage context: use this tool to orient yourself in the project hierarchy before searching. It does not state explicit exclusions or name alternative tools, but the guidance is actionable.

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 carries the behavioral burden and does so excellently. It discloses the side effect of marking handoffs as delivered, the 24-hour disappearance from the default view, and clarifies that the content is data, not instructions. This is exactly the kind of behavioral detail an agent needs to avoid data loss.

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

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

Although the description is long, every sentence earns its place: purpose, distinction, side-effect warning, data-not-instruction warning, filter details, and config override. The 'IMPORTANT:' marker highlights the most critical behavioral trap, and the structure is logical and front-loaded.

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

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

For a list tool with no annotations, no output schema, and a serious side effect, the description covers all essential operational aspects: what it lists, the consumption behavior, the filter options, and the projectName override. An agent can call it correctly and understand the consequences without additional information.

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 description adds significant meaning to the filter parameter by explaining what each enum value returns ('open' = unresolved not delivered in 24h, 'mine' = only addressed to you, 'all' = everything including resolved). For projectName, it gives a concrete precedence rule but does not explicitly define what the parameter represents, leaving some ambiguity.

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 the specific action 'List handoffs' and defines the resource as 'markdown notes from teammates addressed to you or the whole project.' It also distinguishes the tool from tasks ('Not tasks') and, by implication, from single-handoff tools like get_handoff and resolve_handoff, making the purpose unmistakable.

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 strong usage guidance: it warns that calling marks handoffs as delivered and instructs the agent to relay everything immediately. It also explains the filter semantics and the projectName config preference. However, it does not explicitly name an alternative for retrieving a single handoff (e.g., get_handoff), only excluding tasks.

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 behavioral disclosure. It discloses what the tool returns (each question's key, status, and resolution note), which is helpful. It does not explicitly state that the operation is read-only or side-effect free, but the verb 'list' implies non-mutation. This is adequate but not richly 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 two sentences: the first states the purpose and the parameter alternatives, the second describes the return values. Every sentence earns its place with no fluff or redundancy. It is efficiently front-loaded with the core action and resource.

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 two-parameter list tool with no output schema and no annotations, the description covers purpose, parameter alternatives, and return fields. It is complete enough for an agent to call it correctly. Minor gaps like pagination or behavior when no questions exist are not critical for this simple tool, so a small deduction is fair.

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 restates the parameter meanings ('UUID' and 'short key') that are already in the schema's descriptions. It adds the clarification that either parameter can be provided, which slightly reinforces the 'alternative' note already in the schema, but does not add material new 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 states a specific action ('List') and resource ('open questions of an epic'), which clearly separates this collection operation from siblings like get_open_question, create_open_question, and update_open_question. The scope is unambiguous and an agent can identify the tool's purpose 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?

The description implies when to use it (when you need open questions for an epic) and gives parameter usage instructions ('Provide either epicId or epicKey'). However, it does not explicitly exclude alternatives or state 'use this instead of get_open_question', leaving the choice to inference from the verb 'list'.

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 for behavioral disclosure. It reveals key behavior: only owner and accepted members are returned, email is used as a fallback when a member lacks a name, and project selection prefers a workspace config over the API key default. It does not cover error cases or read-only guarantees, but 'List' implies a safe read 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 and front-loaded: the core purpose appears first, followed by disambiguation guidance and project-selection behavior. Every sentence adds necessary information with no filler 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 simple one-parameter list tool with no output schema and no annotations, the description is largely complete. It names the returned fields, explains the fallback email behavior, and clarifies project selection. It could be slightly more explicit about what happens when no projectName is available, but the API-key default is already implied.

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 only defines projectName as a string with 0% description coverage, so the description must compensate. It explains how projectName is selected and that the API key's default project is the fallback, which gives real meaning to the parameter 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 clearly states a specific action ('List the people who can be assigned work in a project') and specifies the exact scope: the owner and accepted members, with names, roles, and ids. This is easily distinguishable from sibling list tools like list_projects and list_tasks, which cover different resource types.

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 actionable guidance: use the id to disambiguate when names collide, and prefer a workspace config's projectName when present. It does not explicitly name alternative tools or state when not to use this tool, but the intended context (assigning work, selecting a project) 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 full responsibility for behavioral disclosure. It adds a specific behavioral detail beyond the tool name: results are filtered by caller access. This informs the agent that not all projects may be returned. It does not mention return format or pagination, but for a zero-parameter listing tool, the core behavior is clearly stated.

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, grammatically complete sentence with no filler. All information is front-loaded and every word contributes to meaning. It is minimal yet sufficient for this trivial 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?

Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is complete. An agent can understand exactly what the tool does and invoke it without missing information. There is no complexity that requires additional detail.

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

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

The tool has zero parameters and the schema is fully covered (no properties). Per the baseline for tools with no parameters, a score of 4 is appropriate. The description adds no parameter-specific information because there are none to document.

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 ('list') and resource ('projects') with a clear scope ('the caller has access to'). It unambiguously distinguishes itself from sibling tools like list_documents or list_epics by naming the exact resource, and there is no ambiguity about what is returned.

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: call this to retrieve all projects the user can access. However, it does not provide explicit guidance on when to use this over alternatives, nor does it mention any exclusions or specific scenarios. Given the simplicity of the tool, the implied usage is adequate, but explicit guidance is absent.

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 behavioral disclosure burden. It adds a useful project-selection rule (prefer workspace config's projectName over API key default) and clarifies filter semantics. However, it does not mention output shape, pagination, sorting, or whether all projects/tasks are returned by default, so some behavioral gaps remain.

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

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

Two sentences, front-loaded with the core purpose, followed immediately by filter guidance and a concise project-selection note. Every sentence 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?

For a list operation with 5 optional parameters and no output schema, the description covers the main selection behavior and project resolution rule well. It lacks explicit pagination/return-format guidance, but an agent can invoke and interpret the result correctly for most 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 60%, leaving projectName and status without full descriptions. The description repeats the filter parameter names and adds value by explaining 'standalone' and the projectName/config precedence, but it does not substantially enrich the semantics of every parameter.

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

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

The verb and resource are explicit: 'List tasks of a project.' The filter list (epicId, status, standalone, assignee) makes the operation specific and distinguishes it from single-task retrieval (get_task) or other list_* 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 states what the tool is for and how filters narrow the list, giving clear usage context. It does not explicitly name alternatives like get_task or say when not to use this tool, but the context is sufficient for an agent to select it for bulk/filtered task listing.

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

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

The description discloses that this is a state-mutating operation, and it explicitly documents the reverse behavior with 'Pass `resolved: false` to reopen it.' This goes beyond the bare schema and makes the reversible nature of the action clear, though it does not describe error behavior or authorization 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 two sentences with no filler. It front-loads the primary action, then gives the when-to-use condition, the reverse operation, and the parameter selection guidance in a compact and well-ordered way.

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

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

The description covers the essential invocation details: what to do, when to do it, how to reopen, and which identifiers to provide. However, with no annotations and no output schema, it leaves gaps around edge cases such as already-resolved handoffs, invalid or duplicate identifiers, and response 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?

With only 33% schema description coverage, the description compensates meaningfully by explaining that `resolved: false` reopens a handoff and that `handoffId` and `key` are alternatives ('Provide either...'). It does not specify what happens if both are passed or define `handoffId` further, but the key disambiguation is present.

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 and resource ('Mark a handoff resolved') and states the exact state transition being performed. It is clearly distinct from siblings like send_handoff, get_handoff, and derive_from_handoff because it targets resolution state rather than sending, reading, or deriving.

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 an explicit trigger condition: call this once the handoff content has been acted on or relayed and the user considers it closed. It does not list exclusions or explicitly name alternatives, but the context is clear enough that an agent can decide when to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses meaningful behaviors: returns chunks with citations, projectName fallback logic, and workspace config precedence. It does not mention auth, rate limits, or output structure, but for a search tool this is substantial coverage.

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 sentences with zero filler. The purpose, output, and edge-case behavior are front-loaded, and every sentence provides necessary information.

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

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

For a 5-parameter search tool with no output schema, the description covers purpose, output type, and the trickiest parameter behavior (projectName). It could explicitly explain topK or pathPrefix, but those are already documented in the schema, so the description 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 coverage is 80%, and the description adds significant nuance for projectName—default project behavior, fallback to all projects, and VSCode config override. It also clarifies query semantics through 'semantic search'. topK lacks a schema description and is not explained here, but the high coverage plus projectName detail supports a 4.

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 ('Search across documents using semantic search') and identifies the output form ('relevant chunks with citations'). It distinguishes the tool from list/get siblings by emphasizing semantic search, though it does not explicitly name 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?

It gives clear usage context: use the returned chunks to answer the user's question directly, and it explains project-selection behavior (API key default, fallback to all projects, and VSCode config precedence). It does not explicitly state when not to use the tool or name sibling alternatives, preventing a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses two important behaviors: showing the final text to the user before sending, and never including secrets/API keys/other people's data. While it doesn't mention return values or error handling, these are minor for a simple send operation, and the stated constraints are critical and well-communicated.

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, front-loaded with the core purpose, followed by the usage condition and critical behavioral rules. Every sentence adds distinct value, and there is no redundant or filler 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 simple two-parameter tool with a clear schema and no output schema, the description covers the essential context: when to call, what to include, and what constraints to follow. It omits details like success/failure responses, but these are likely self-evident for a feedback send and not critical 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 coverage is only 50% (message has a description, kind does not). The description adds meaning to 'kind' by enumerating 'bug report, idea, other' which matches the enum, and it enriches 'message' with the privacy constraint ('Never include secrets...'). This compensates for the partial schema coverage and clarifies the expected content of both parameters.

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 ('Send'), a resource ('feedback'), and the recipient ('Bilg team'), along with the categories ('bug report, idea, other'). It clearly distinguishes this from any sibling tool, and there is no ambiguity about what action it performs.

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

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

It gives an explicit trigger condition: 'Only call this when the user explicitly asks to send feedback to Bilg.' It also provides a prerequisite instruction ('Show them the final text first') and a data-handling rule, making it unambiguous when and how to invoke the 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 are provided, so the description bears the full burden of behavioral disclosure. It reveals key behavior: a handoff is a relayed message rather than an actionable task, and the recipient's agent must not act on it. It also discloses a specific projectName precedence rule based on a local config file, which is genuinely useful 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 compact, roughly four sentences, and front-loads the core purpose and the critical 'not a task' distinction. The final sentence about the workspace config is dense but earns its place as important behavioral guidance. There is minimal waste, though it could be tightened slightly.

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 seven parameters, no annotations, and no output schema, the description supplies enough to select and invoke the tool correctly: purpose, recipient semantics, optional linking, and project selection behavior. It omits explicit alternative routing and return/error expectations, but the required parameters are documented in the schema and the behavioral caveats cover common misuse.

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 high at 86%, placing the baseline at 3, but the description adds real semantic value. It explains epicKey and taskKey as linking options, inReplyTo as replying to a previous handoff, and recipient targeting as a person or the whole project. It also adds context for projectName, which has no description in the schema, by specifying the local-config precedence.

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 and resource: 'Leave a handoff for a teammate' and defines it as a markdown note addressed to a person or the whole project. It explicitly differentiates it from task-related siblings with 'This is NOT a task — it is a message.'

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 context by stating what a handoff is not and how the recipient's agent must behave: it will relay the note but must not act on it unilaterally. It also indicates when optional epicKey, taskKey, and inReplyTo links are appropriate. It does not explicitly name alternative tools beyond the task comparison, so it stops short of full exclusion 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 are provided, so the description carries the full burden. It discloses an important authorization behavior: only the author can edit. However, it does not mention what happens if the comment is not found, whether the update replaces the entire body, or any response 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 two short sentences with no wasted words. 'Edit a comment' front-loads the purpose, and the author restriction earns its place as crucial usage context.

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 two-parameter update tool, the description is adequate but missing details about error handling, response format, and whether the body replaces the entire comment. With no annotations and no output schema, more context would be helpful.

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 covers 'body' with a description, but 'commentId' has no description. The tool description does not explain either parameter or add meaning beyond their names. With schema coverage at 50%, the description should compensate but does not.

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 'Edit a comment' with a specific verb and resource. It is obviously distinct from sibling tools like add_comment or update_document, though it does not explicitly name them. It misses the top score because it lacks explicit differentiation 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 includes a usage constraint ('Only the comment's author can edit it') but does not say when to use this tool versus alternatives such as add_comment or update_task. There is no guidance on selecting this tool over other update tools.

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

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

With no annotations, the description carries the behavioral burden, and it handles it well: it discloses the destructive nature ('Replace the entire content') and the safety net ('Previous version is saved to history'). It does not cover permissions or failure modes, but the key mutation and recovery behavior is 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?

Two sentences with no filler; the primary operation is stated first and the version-history fact is a valuable second sentence.

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 3-parameter mutation tool with no annotations and no output schema, the description covers required semantics and the main side effect. The only notable omission is an explanation of the optional changeNote, but this is a low-severity gap given the required params are obvious.

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 content has a schema description (33% coverage), and the tool description adds no new details about documentId or changeNote. The phrase 'entire content' restates the content parameter's 'New full content' rather than explaining how to format it or what changeNote is for.

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 ('Replace'), names the resource ('existing text document'), and clarifies scope ('entire content'), distinguishing it from append_to_document and update_document_metadata. There is no ambiguity about what operation is performed.

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

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

The phrase 'Replace the entire content' implies this tool is for full-content overwrites rather than appends or metadata edits, but it never states the alternative conditions or explicitly says to use append_to_document for additions. An agent must infer the selection rule from sibling names.

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 usefully discloses that content is untouched and that no version snapshot is created, but it omits permissions, reversibility, and what happens to unspecified metadata fields.

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, front-loaded sentences with no filler. The main action and the key caveat about version snapshots are stated immediately and 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?

The description is adequate for basic invocation with a documentId plus metadata fields, and it covers the most important behavioral constraint. However, it does not state whether at least one metadata field is required, what the response looks like, or whether changing path moves the document, leaving some gaps given the lack of an output schema and annotations.

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

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

Schema description coverage is 0%, so the description must compensate, but it mostly repeats the property names (title, path, tags) without explaining their semantics. It does not clarify path behavior, whether tags replace or append, or the format of documentId, leaving significant meaning to inference.

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 and resource ('Update document metadata') and names the exact fields involved: title, path, tags. It also differentiates from content-focused document tools by explicitly stating 'without changing content' and 'No version snapshot is created.'

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 establishes this tool is for metadata-only changes and implicitly excludes content edits, giving the agent a clear boundary. It does not name the alternative tool for content changes (e.g., update_document), but the context is clear enough for 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?

Since no annotations are provided, the description carries the full burden, and it delivers. It discloses rejection behavior ('the server rejects them otherwise', 'Setting a stage the project has turned off is rejected'), the locked state after deployment, and the human-only transition boundaries. It also explains prerequisite conditions for acceptance/ready statuses (no open tasks or unresolved questions). This is far more transparent than typical tool descriptions.

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 long, but every sentence earns its place by adding either a constraint, a prerequisite, or an exclusion. It front-loads the core action and partial-update rule, then systematically walks through the status workflow. The density is justified by the tool's complexity; no filler or repetition was found.

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 complex state transitions and lack of annotations/output schema, the description is quite complete: it covers the full progressStatus lifecycle, rejection conditions, human-only actions, locking, and assignment scoping. It does not mention authentication/permissions or return values, but with no output schema those are minor; the state-machine guidance is the critical context and it is thoroughly addressed.

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 only 22%, so the description must compensate, and it does for the most complex parameters: progressStatus gets a full maturity model with exact conditions for each stage, disabledReason gets clear toggling semantics, and planStatus/active are given a concrete usage pattern. It leaves owner, title, description, and documentId with no added meaning, but those are relatively self-explanatory compared to the status state machine.

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

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

The description opens with 'Update an epic' – a clear verb+resource statement – and immediately clarifies the partial-update behavior with 'Pass only the fields to change.' It goes beyond the bare action to explain core fields (disabledReason, planStatus, progressStatus), which uniquely distinguishes this from create_epic, get_epic, and list_epics without needing to inspect those schemas.

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?

This is exceptionally strong: it gives explicit when-to-use conditions ('When you start working on an epic set planStatus=now and active=true'), exclusions ('deployed is human-only... never available to agents'), conditional rules ('Moving past that stage to the next one is for the human, unless the user explicitly asks for it'), and a scoping guardrail ('Work only on items assigned to the user unless told otherwise'). It leaves no ambiguity about when this tool should be invoked versus when to refrain.

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 behavioral burden. It spells out state transitions: edit text, mark resolved/unresolved, set or clear a resolution note, and change askedTo. 'Pass only the fields you want to change' also tells the agent that omitted fields are left untouched, which is important update 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?

Two efficient sentences cover the operation, the editable aspects, the identifier choices, and the patch semantics. No filler or redundancy; the key usage constraints are front-loaded.

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

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

For a six-parameter tool with no output schema, the description gives enough information to invoke it correctly: identifier alternatives and which fields can be mutated. It omits response details and error behavior, but the input-side semantics are sufficiently 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 50%, and the description compensates by explaining questionId is a UUID, clarifying that key is the alternative identifier, and mapping intended changes to fields. The partial-update rule is essential semantics that is not fully captured by 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 starts with the specific verb-resource pair 'Update an open question' and then enumerates the concrete kinds of changes: text, resolved state, resolution note, and askedTo. This makes it clearly distinguishable from create_open_question, get_open_question, and list_open_questions.

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

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

It gives explicit invocation guidance: 'Provide either questionId (UUID) or key (short key)' and 'Pass only the fields you want to change', which clarifies the partial-update model. It does not name alternatives or exclusions, but the update intent is clear enough that an agent knows when to choose 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?

No annotations are provided, so the description must carry the behavioral burden. It discloses that this is a partial update ('Pass only the fields to change') and sets a soft safety rule on assignment and priority. It also clarifies the relationship between description and documentId. While it doesn't state explicitly that changes are irreversible or highlight side effects, the partial-update framing and priority/assignment cautions give adequate transparency 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?

The entire description is one focused paragraph with no filler. The first sentence states the core action, and each subsequent sentence adds a specific, necessary rule (partial update, description vs document, assignment scope, blocked reason, priority). It is front-loaded with the most important information and every sentence earns its place.

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

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

For a tool with 12 parameters, low schema coverage, and no output schema, the description covers the critical behaviors: partial updates, the summary-vs-document pattern, assignment constraints, blocked status requirements, and priority handling. It doesn't mention return values, but as an update tool that is less critical. The main omissions are details on fields like title/size/type, but those are self-evident. Overall it provides sufficient context for an agent to call the tool 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 only 42%, so the description must compensate. It does: it explains that description is for summaries, that documentId links a spec document, that blockedReason is only for blocked status, and that priority should not be invented. It also implies that status supports 'done' and epic moves. It doesn't add context for every parameter (e.g., size, type, title), but it covers the ones that carry ambiguity, making the field meanings more concrete than 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 opens with 'Update a task,' a clear verb+resource, then immediately gives concrete use cases: 'mark a task done (status: 'done') or move it between epics.' It also specifies behavioral rules like not inventing priority. This strongly distinguishes it from creation/list tools and tells an agent exactly what the tool is for.

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: to mark done, move epics, and set status. It also gives negative guidance: 'Work only on items assigned to the user unless told otherwise; see list_tasks assignee='me'' and 'Don't invent priority.' It also advises creating a document for detailed specs instead of long descriptions. It doesn't explicitly name sibling tools like update_task_comment, but it does give clear context for when this update 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?

With no annotations provided, the description carries the full burden. It discloses that the operation is a read-only 'Show' action and explains the conceptual purpose of the returned identity, which is beyond what the empty schema provides. It does not explicitly state 'has no side effects,' but the read verb and identity focus make that sufficiently clear.

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 one compact sentence that front-loads the action, target, and returned fields, then adds the agent-relevant framing. Every clause earns its place and there is no redundant or filler 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?

For a zero-parameter, read-only identity tool, this description is complete. It names the resource, the exact fields returned, and the operational meaning ('who the agent is acting as'). No output schema exists, but the described return fields are sufficient for an agent to know what to expect.

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

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

The tool has zero parameters, so there is no parameter meaning for the description to add. The schema fully covers parameter requirements, and the description instead clarifies the meaning of the returned identity, which 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 a specific verb ('Show'), a specific resource ('authenticated Bilg user'), and the exact fields returned (name, email, id). This clearly distinguishes the tool from the document, task, and handoff siblings, which operate on entirely different resources.

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

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

The phrase 'who the agent is acting as' provides clear context for when to call this tool: whenever the agent needs to verify its own identity. There are no sibling tools with similar identity purposes, so explicit alternatives are not necessary, though no when-not-to-use guidance is given.

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