Brain Scanner

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this is a destructive, idempotent mutation. The description adds that staged data is released and that the sync must be uncommitted, which is useful. It does not describe required permissions, what happens to partially appended chunks, or whether the abort is reversible.

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

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

Single sentence, no wasted words, and the key constraint 'uncommitted' is front-loaded with the action.

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

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

For a destructive sync mutation with no output schema, the description covers the basic effect but omits important context such as what 'staged data' comprises, whether in-flight chunks are discarded, and how it relates to commit/seal. Annotations cover the safety profile, but the description could be richer for an agent deciding whether to call it.

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

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

Schema description coverage is 100%, so the five parameters are already documented. The description adds no parameter-level detail, which is acceptable at high coverage but leaves no extra 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?

States a specific verb (abort) and resource (hosted graph synchronization) with the scope 'uncommitted' and the effect 'release its staged data'. This distinguishes it from siblings like commit_project_sync, seal_project_sync, and clear_project_graph, though it doesn't explicitly name 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 word 'uncommitted' implies this is for abandoning an in-progress sync, which gives some usage context. However, there is no explicit when-to-use versus when-not, no mention of alternatives like commit_project_sync, and no prerequisites or error conditions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description needs to explain what is destroyed or how acknowledgement state changes; it does neither. "Privacy-filtered project metadata" is unexplained and adds no operational context such as auth requirements, side effects, or what a stale expectedVersion implies.

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

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

A single sentence with no filler, and the verb leads. It is efficient, if only because it says so little; nothing is padded or buried.

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

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

For a mutation tool with eight required parameters, a destructive annotation, no output schema, and a version-conflict parameter, one vague sentence is far from sufficient. The description leaves the agent without the mutation semantics, the acknowledgement effect, or any notion of what success returns.

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 high (~88%), so the baseline is 3, and the description adds nothing about the eight required parameters. This is generous given that five parameters (taskId, controlId, projectId, sessionId, executionId) carry identical boilerplate "Owned project ID" text that is almost certainly wrong.

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?

It gives a verb ("Update") and a resource ("acknowledge instruction control"), but the resource is dense internal jargon and the verb conflicts with the tool's own name, which implies an acknowledge action rather than an update. An agent cannot confidently tell it apart from siblings like control_instruction_task or submit_node_instruction.

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?

There is no statement of when to use this tool, when not to, or which sibling handles the adjacent case (e.g. queue_instruction_tasks vs control_instruction_task). The one clause about "privacy-filtered project metadata" gestures at a constraint but gives no actionable condition.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description adds real context: it is append-only metadata and it does not execute the described activity. However, 'Effects and required fields depend on that operation' is a non-disclosure for a dispatcher with exactly one operation, leaving mutation effects unstated.

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

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

Front-loaded with the actual effect and the non-effect in the first sentence, and the whole thing is four compact sentences. The trailing 'Effects and required fields depend on that operation' is padding given a single supported operation.

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 write tool with full annotation coverage and a 100%-documented schema, the definition covers purpose, dispatch semantics, and the key non-effect. It lacks a statement of the resulting state on success, but with no output schema required and safety already annotated, nothing essential is missing.

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

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

Schema description coverage is 100% and the schema is unusually rich (idempotencyKey guidance, projectId sourcing, bounded details), so the schema does the heavy lifting. The description only restates the dispatch shape ('Select operation and its matching payload') without adding format or constraint meaning beyond it.

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 ('Append bounded activity metadata to the project history') and immediately clarifies what it does NOT do ('does not execute the activity being described'). It also distinguishes itself from siblings by labeling itself a compatibility dispatcher that should be skipped in favor of the individually named tool, so an agent can tell it apart from record_activity.

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

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

Explicitly routes the agent: 'prefer the individually named tool when available,' which names the alternative (record_activity) and the condition for preferring it. It stops short of stating the positive trigger (use this only when the named tool is unavailable) and gives no exclusions beyond that.

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

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

Annotations only tell the agent this is a non-destructive idempotent mutation; the description adds the crucial caveat that 'the hosted server does not open editors or execute tests', which prevents a false expectation that open_node_in_editor or run_selected_tests has real local side effects. It does not explain what each operation actually records.

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

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

Front-loaded with the core purpose, then the compatibility caveat, then the operation list — no filler. The operation list is necessary because the enum alone would not tell an agent these are individually callable tools.

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 five-branch oneOf dispatcher with no output schema, the description covers scope and the server-side limitation, but per-operation semantics are thin: the branches only say 'Select this exact operation', so an agent gets no help choosing between, say, start_node_work and relay_execute_local_action. It partially compensates by deferring to the named sibling tools.

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

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

Schema description coverage is 100% and the oneOf branches carry per-field documentation, so the baseline is 3. The description adds only the framing that 'effects and required fields depend on that operation', which is marginal beyond what the branch structure already conveys.

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

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

States a specific verb and resource ('Record pending local-agent action requests and their outcomes') and enumerates the five supported operations, so the agent knows this is a multi-operation dispatcher. It also flags its compatibility role, distinguishing it from the identically-named sibling tools, though it does not differentiate the operations from one another.

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?

'Compatibility dispatcher; prefer the individually named tool when available' gives an explicit selection rule against the alternatives in the sibling list (finish_node_work, open_node_in_editor, etc.). It stops short of stating the inverse condition — when this dispatcher is genuinely the right choice — but the routing guidance 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one behavioral trait beyond that — that results are 'privacy-filtered' — which is useful context, but it says nothing about pagination behavior or what the impact result contains.

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

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

A single short, front-loaded sentence with no filler or redundancy. It is concise, though the brevity comes at the cost of substance rather than being a model of tight, informative phrasing.

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 analysis tool with no output schema, the description is far too thin — it never explains what an impact analysis computes, how nodeIds/executionId/sessionId shape the result, or what the agent should expect back. Annotations cover safety but not the analytical 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 100%, so the schema already documents all six parameters in detail (cursor, nodeIds, pageSize, projectId, sessionId, executionId). The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description restates the tool name ('analyze impact') without explaining what an impact analysis actually is, what it operates on, or what it returns. 'Read hosted analyze impact' is close to a tautology, and no sibling is named or distinguished despite many neighboring graph/analysis tools.

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

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

There is no when-to-use guidance, no prerequisites, and no indication of which alternative tools to pick instead. The phrase 'using privacy-filtered project metadata' hints at the data source but does not tell the agent when this tool is the right choice.

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

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

Annotations already declare the safety profile: idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds 'privacy-filtered', which hints that filtering happens server-side, but it says nothing about ordering requirements across chunks, digest validation, retry semantics beyond the idempotencyKey schema note, or what happens on a rejected chunk. Adequate but shallow given annotations carry the safety story.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though it is arguably too terse for the operation's complexity rather than padded.

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-required-parameter mutation with nested node/edge payloads, a 64-hex digest, an ordered chunk index, and no output schema, one sentence leaves the agent without sequencing rules, size/limit expectations, or failure behavior. The only compensating detail is the idempotencyKey schema note.

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 50%, and the description covers zero parameters. Critical fields like chunkIndex (0-511), chunkDigest, and chunkSize have no description in either place, yet the agent must understand that chunks are ordered and digest-verified. 'One chunk' is the only parameter-adjacent signal, which does not compensate for the coverage gap.

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 names a specific verb and resource: appending one chunk of graph metadata to a hosted synchronization. That distinguishes it from begin_project_sync, commit_project_sync, and seal_project_sync in the sibling list. It does not explicitly contrast itself against those siblings, so it falls short of a 5.

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

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

There is no when-to-use guidance, no prerequisite stated (e.g., begin_project_sync must precede it), and no mention of the sibling tools this step must be ordered against. The mid-sync positioning is only implied by the word 'append'.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety/idempotency profile is covered. The description adds only the vague phrase 'using privacy-filtered project metadata' and does not explain what is mutated, conflict/versioning behavior, or permissions beyond what annotations and schema already state.

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

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

A single short sentence with no padding, so it is concise, but it is concise at the cost of being uninformative rather than front-loading useful detail. Appropriate size is not the issue; content is.

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

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

For a mutation tool with 11 required parameters, no output schema, and version-conflict semantics implied by expectedVersion/expectedProjectVersion, the description is grossly inadequate. It neither explains the operation nor helps an agent understand the preconditions or outcome.

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 55%, and the description contributes no parameter meaning at all. Several parameters (graphDigest, resultSummary, resultingMeterKey, baseSourceFingerprint, resultingSourceFingerprint) have no schema descriptions either, so the burden is unmet. The schema also contains a copy-paste defect where requestId and sessionId reuse the projectId description, which the description does nothing to resolve.

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 largely restates the tool name ('Update hosted apply implementation meter change'), which is essentially a tautology. It does not clarify what an 'implementation meter change' is or how it differs from close siblings like queue_implementation_meter_request or get_pending_implementation_meter_changes.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. An agent cannot tell from this text whether it should call this tool or the closely related queue_implementation_meter_request / get_pending_implementation_meter_changes siblings.

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

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

Annotations already declare this is a non-destructive, idempotent, closed-world mutation, so the safety profile is covered. The description adds only the phrase 'privacy-filtered project metadata', which is vague and does not disclose what archiving does to the note, whether it is reversible, or how version conflicts are handled — all relevant for a mutation with an expectedVersion guard.

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

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

A single short sentence with no filler, which is structurally clean. However, its brevity comes at the cost of under-specification rather than efficient communication, so it does not fully earn its place.

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

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

This is a 7-parameter mutation with a nested object, an idempotency key, an expectedVersion concurrency guard, and no output schema. For that complexity the description is far too thin — it says nothing about what archiving changes, conflict behavior, or retry semantics that the agent must reason about.

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 every parameter already carries its own guidance, and the baseline is therefore 3. The description's 'privacy-filtered project metadata' loosely gestures at the bounded details object but adds no syntax or constraint information beyond what the schema states.

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

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

The description gives a verb ('Update') and a resource ('hosted archive context note'), but it is ambiguous whether the tool archives a note or edits a note that lives in an archive, and the word 'Update' conflicts with the 'archive_' prefix in the name. With siblings like update_context_note, delete_context_note, move_context_note and convert_context_note, the description does nothing to distinguish this tool from 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?

There is no statement of when to use this tool versus update_context_note or delete_context_note, and no prerequisites or exclusions are given. 'using privacy-filtered project metadata' hints at a constraint but does not tell the agent when this operation is the right choice.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds only one behavioral nuance ('privacy-filtered project metadata') and says nothing about what is written, side effects, or auth needs. Notably, the name implies creating/starting an execution while the description says 'Update', an internal inconsistency, though it does not contradict the annotations.

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

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

It is a single sentence with no filler, which is structurally tight, but for a nine-parameter mutation tool the sentence is under-specified rather than genuinely concise, and its verb/resource phrasing is muddled.

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 nine-parameter write tool with no output schema and incomplete schema descriptions, the one-line description leaves the agent without enough to call it correctly. The safety annotations help, but the purpose, usage, and parameter meaning are all left largely unexplained.

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?

Nine parameters with only 56% schema description coverage, and the description contributes zero parameter information — no explanation of executionId, trigger, projectIds, or requestMetadata. It fails to compensate for the undocumented half of 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 largely restates the tool name ('Update hosted begin agent execution'), adding only the cryptic qualifier 'using privacy-filtered project metadata'. It never states what an execution record is or what the write accomplishes, and it gives no basis to distinguish it from siblings like finalize_agent_execution, get_agent_execution_status, or record_agent_execution_activity.

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?

There is no statement of when this tool should be used, no prerequisites, and no mention of alternatives among the many execution/session siblings. The agent must infer usage entirely from the name.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world behavior. The description adds two useful behavioral facts — that the sync is 'bounded' and that the changeNarrative must be hand-written rather than generated — but says nothing about locking, resumability, partial-failure behavior, or what a successful begin returns.

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

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

A single sentence with no filler, and the most important scoping information (bounded graph sync) is front-loaded. 'Bounded' is doing a lot of unexplained work for one word, but the sentence itself is efficient.

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?

Twelve parameters, nine required, a nested object, no output schema, and a 42% coverage schema, yet the description does not explain the declared* size declarations, the concurrency role of expectedProjectVersion, or the sync lifecycle (status polling via get_project_sync_status, abort_project_sync on failure). For a protocol-entry mutation this leaves substantial gaps.

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

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

Schema description coverage is only 42% across 12 parameters, so the description should compensate more than it does. It does clarify the semantics of changeNarrative ('four plain-language sections written manually'), which maps to the nested object, but the four declared* count parameters, sessionId/executionId, and mappedRevision remain unexplained beyond the schema.

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

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

States a specific verb (Begin) and resource (hosted graph synchronization) and adds the key constraint that it is bounded and that changeNarrative is supplied by the publishing agent. It does not name the sibling flow steps (append_project_sync_chunk, commit_project_sync, seal_project_sync), so the agent must infer this is the entry point of a multi-call protocol.

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?

There is no explicit when-to-use or when-not guidance, and no mention of the alternative tools (graph_sync, publish_project_graph, patch_project_graph) or of the required follow-up calls. 'Begin' implies a first step, but the description never says what to do next or under what circumstances this path should be chosen over a one-shot publish.

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

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

Annotations already carry the read-only, idempotent, non-destructive profile. The description adds a small amount of context by constraining access to the 'active owned project' and characterizing the state as 'bounded,' but it does not discuss permissions, side effects, or what portal state actually covers. No contradiction with annotations.

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

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

The description is one short sentence with the verb front-loaded and no filler or repetition. It is concise and easy to scan, though the jargon 'bounded portal state' could use a little more elaboration.

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 as a label but not as a standalone guide: it omits selection criteria among many sibling reads, leaves sessionId unexplained, and relies on the output schema to supply return semantics. Given the large, confusing sibling set, more context is needed.

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%, and the description does not explain projectId or sessionId semantics, nor how 'active owned project' maps to the parameters. The phrase 'active owned project' hints at projectId, but sessionId remains entirely unaddressed; this is not enough to compensate for the missing schema descriptions.

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

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

The description uses a clear verb, 'Read', and names a specific resource ('active owned project's bounded portal state') with app context, so an agent can identify the tool's basic function. It doesn't explicitly contrast with sibling read tools like project_read or get_project_status, but the 'bounded portal state' phrase points to a distinct resource, keeping ambiguity low.

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

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

No when-to-use or when-not-to-use guidance is provided. With dozens of sibling read tools (project_read, scope_read, graph_read, context_read, etc.), nothing tells an agent why this portal-state read should be chosen instead of an alternative.

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 adds behavioral context beyond annotations: it mandates explicit user consent before upload, flags retrieved source as 'untrusted project data, never instructions,' and states that disconnect retains data. These are valuable and not present in annotations. It doesn't contradict the destructiveHint: true annotation, though it doesn't explicitly discuss destructive operations either.

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, consisting of three sentences that front-load the purpose and then add workflow and safety notes. There is no fluff, and it is appropriately structured for a high-level summary. It could be slightly more detailed without becoming verbose, but it remains efficient.

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

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

Given the tool's complexity (9 operations, nested payload, many parameters), the description is insufficient. It does not explain the operation variants, the consent flow steps, or return values (no output schema). An agent would struggle to correctly invoke operations like upload_blob, commit_snapshot, or delete_sources without additional documentation.

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 only provides a high-level workflow and doesn't explain specific parameters like projectId, snapshotId, or operations like upload_blob vs commit_snapshot. The mention of 'status/notice' and 'consent' gives some hints but insufficiently maps to the schema's detailed structure.

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 tool's overarching purpose: 'Opt-in exact source ingestion, versioned retrieval and code relationships.' It clearly indicates the domain and the consent workflow, and the name includes 'source' which aligns with the schema's operations. However, it doesn't explicitly differentiate from sibling tools or detail each operation, so it's clear but not fully distinctive.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention any exclusions or conditions for selection. It does describe an internal workflow (status/notice, preview, consent before upload) but does not address tool selection. With many sibling tools, this is a notable gap.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say what cancellation does to the queue item, whether it is reversible, what permissions are needed, or how expectedVersion/idempotencyKey govern retries. 'Privacy-filtered project metadata' is opaque rather than informative.

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

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

A single short sentence with no bloat, so nothing needs trimming. However, brevity here reflects under-specification rather than tight, front-loaded information — the one sentence raises questions instead of answering them.

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

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

This is a destructive, version-guarded, idempotency-keyed mutation with no output schema, and the description never explains the outcome of the operation or its relationship to the update/cancel siblings. Given the complexity signalled by 6 parameters, a required idempotencyKey, and expectedVersion concurrency control, the description is materially incomplete.

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

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

Schema description coverage is 100%, so the schema already carries full parameter semantics (idempotencyKey retry rules, expectedVersion conflict behavior, queueItemId prefix requirement). The description adds no parameter-level meaning, so the baseline of 3 applies. Note the sessionId/executionId schema descriptions are duplicated from projectId, but that is a schema issue, not a description one.

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 name says 'cancel' but the description says 'Update hosted cancel queue item', so the verb and the actual effect are left ambiguous — an agent cannot tell whether this cancels or merely edits the item. The resource is named but there is no differentiation from close siblings like update_queue_item, cancel_queue_type, or preview_queue_type_cancel. The phrase 'using privacy-filtered project metadata' adds opacity rather than clarity.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite several directly competing siblings (update_queue_item for edits, cancel_queue_type for type-level cancels, list_queue_items for discovery). The agent is left to infer everything from the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered by structured data. The description adds only the vague phrase 'privacy-filtered project metadata' and never discloses what is destroyed, that a preview/commit ordering exists, or what the idempotency key protects against.

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

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

A single short sentence with the verb-resource pairing front-loaded, so it is appropriately sized. However, the phrasing is garbled ('hosted cancel queue type') and none of the limited space is spent on anything useful.

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 destructive mutation that requires an idempotency key, a snapshot version, and a preview digest, with no output schema and no annotations beyond safety hints, the description omits the entire preview/commit workflow and any returned-result guidance. An agent lacks the information needed to invoke this safely.

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

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

With 57% schema description coverage and no parameter detail in the description, the bare sessionId/executionId/requestType fields and the previewDigest/snapshotVersion semantics are left undocumented. The description contributes nothing beyond the schema, so it fails to compensate for the coverage gap.

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

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

Names a resource ('cancel queue type') but pairs it with the verb 'Update', which conflicts with the tool name 'cancel_queue_type' and the sibling 'preview_queue_type_cancel'. An agent cannot tell whether this cancels a queue-type operation or edits a queue-type configuration, and the phrase offers no 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?

No when-to-use, when-not-to-use, or alternative is given. Notably absent is any mention of the apparent preview-then-commit relationship with preview_queue_type_cancel, despite required previewDigest/snapshotVersion fields implying a prior preview call.

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

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

Annotations already declare idempotentHint, destructiveHint=false and openWorldHint=false, so the description's real contribution is the 'advisory' semantics — claims expire on their own and never block a publish — which meaningfully tells the agent the claim is not a hard lock. It omits TTL behavior detail (60–3600s range), auth requirements, and what happens on a conflicting claim.

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, front-loaded with the purpose and followed by the two behavioral caveats that matter most. No wasted words.

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

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

For a 6-parameter mutation with no output schema, the description covers the concept but not the contract: it does not say what a successful claim returns, how a conflicting claim is surfaced, whether release_map_scope must eventually be called, or what ttlSeconds defaults to. Adequate, but gaps remain an agent would want filled.

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 50% and the description mentions no parameter at all. scopePrefix, agentId, ttlSeconds and sessionId have no documented meaning anywhere, and the scopePrefix path-safety pattern and TTL bounds are left for the agent to infer from the JSON 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?

States a specific verb (claim) and resource (repository subtree / scope) with its rationale (so concurrent mappers avoid overlapping work). An agent can tell this is a coordination primitive rather than a data read/write, though it never names the counterpart sibling release_map_scope to disambiguate the pair.

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 advisory nature and the fact that claims 'never block a publish' imply when this is appropriate (soft coordination before mapping a subtree), but there is no explicit statement of when to call it versus release_map_scope, get_ownership, or inbox_claim, and no prerequisites named.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds real value beyond them by disclosing recoverability ('Prior versions stay restorable within retention') and the manual changeNarrative obligation, which the annotations do not convey. It does not detail post-reset state or side effects on sessions.

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

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

Three tight sentences, front-loaded with the core action and no redundant restatement of the name. Each sentence carries distinct information (action, recoverability, narrative requirement), though the split could be slightly tighter.

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 destructive mutation with full annotation coverage and no output schema, the description supplies the key operational facts: it is explicit/auditable, recoverable within retention, and requires a manually authored four-part narrative. Missing only auth/permission requirements and the exact post-reset state.

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 80%, so the baseline is 3; projectId, sessionId, idempotencyKey, and expectedProjectVersion are documented in the schema. The description adds only marginal meaning for changeNarrative ('four plain-language sections, manually written') without explaining what each section should contain, so it does not fully compensate for the undocumented 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 gives a specific verb+resource: 'Reset the published graph to empty,' which is distinct from publish_project_graph, patch_project_graph, and export_project_graph. It stops short of explicitly naming a sibling alternative (e.g., restore_project_version), but an agent can still distinguish the reset-to-empty action.

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 frames the call as 'an explicit, auditable operation' and notes prior versions remain restorable, which hints at intent, but there is no explicit when-to-use/when-not guidance or routing to alternatives like restore_project_version. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds the useful atomicity guarantee, but says nothing about what the destructive publish replaces, version-conflict failure behavior, or auth requirements.

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

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

A single front-loaded sentence with zero filler. However, for a destructive, 7-parameter commit operation it is arguably too terse, leaving no room for the operational context the tool warrants.

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

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

This is a destructive, non-idempotent-by-default mutation in a multi-step sync lifecycle, with no output schema and no explanation of the begin/append/seal/commit sequence or failure modes. An agent has to reconstruct the workflow entirely from sibling tool names.

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

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

Schema description coverage is 86%, so the schema documents nearly all parameters (including the version guard and idempotency key semantics). The description adds no parameter-level meaning, which is acceptable at this coverage level.

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 ('publish') and resource ('sealed hosted graph version') with a meaningful qualifier ('atomically'). An agent can infer this is the terminal step of a seal/commit flow distinct from seal_project_sync, though the description never names that sibling relationship explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no alternatives named. The word 'sealed' hints that a sealing step must precede this, but the agent is left to infer the sequencing from sibling names alone.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true and closed-world, so the safety and retry profile is largely covered. The description adds one genuine behavioral fact beyond that: blocked/failed work stays active rather than being closed. It says nothing about required permissions, what state a successful completion transitions to, or concurrency behavior beyond what expectedVersion in the schema already implies.

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, each carrying a distinct rule, with the state-preservation fact front-loaded right after the core action. Dense but not padded; no sentence is purely decorative.

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 7-parameter mutation with a nested details object, no output schema and version-based concurrency, the description covers success conditions but omits return/effect semantics and does not compensate for the misleading parameter docs. Adequate minimum, with clear gaps an agent would hit on first 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?

Schema description coverage is 100%, so the 3 baseline applies. The description does add one useful hint beyond the schema by tying details.status=resolved to finding resolution, but several schema descriptions are visibly wrong (taskId, details.status, sessionId and executionId are all documented as 'Owned project ID returned by list_linked_projects'), and the description does not correct that confusion.

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

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

The description opens with 'Record a versioned result' and gives conditional outcomes ('blocked/failed work stays active', 'Resolve a finding...'), which implies completion but never plainly states that this tool completes an inbox task. A named sibling like inbox_claim/inbox_start is not contrasted, so the agent must infer scope from the name alone rather than the prose.

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 supplies real conditional guidance: roadmap completion 'requires published meter advancement and confirmed evidence', and resolving a finding needs details.status=resolved plus a verification summary. That tells the agent when the call will succeed. It stops short of naming alternative tools or exclusions, so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the dispatcher nature and the hedge that 'Effects and required fields depend on that operation,' without describing what the operations actually do or produce. Minimal added behavioral context beyond structured data.

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

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

Front-loaded with the dispatcher role and the preference to use named tools, followed by the operation list. Four short sentences, none obviously redundant, though 'Effects and required fields depend on that operation' is filler that restates the polymorphic 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?

For a compatibility shim whose parameters and safety are fully covered by schema and annotations, the description is adequate. It stops short of explaining the difference between get_context_graph and get_context_overview, which an agent must choose between when the named tools are unavailable.

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 'operation' and 'payload' with enum consts per branch. The description's 'Select operation and its matching payload' reinforces the oneOf dispatch contract but adds no syntax or format detail beyond what the schema provides — baseline 3.

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

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

The description states it is a 'Compatibility dispatcher' for context read operations and enumerates the two supported operations (get_context_graph, get_context_overview), so the agent knows exactly what it routes to. The verb 'Access' is generic, but the dispatcher framing plus the operation list makes the purpose concrete enough to distinguish this from write/other read tools.

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

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

It gives explicit routing guidance: 'prefer the individually named tool when available,' which tells the agent this is a fallback path. It does not, however, explain when each of the two operations (graph vs overview) is appropriate, so the choice inside the dispatcher is left to the named siblings.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds only the caveat that 'effects and required fields depend on that operation', which is honest but uninformative — it does not say which of the nine operations mutate, archive, or rebuild anything, so an agent gains little behavioral insight.

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

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

Front-loaded with purpose and the fallback guidance, then the unavoidable operation list. Every element earns its place, though the third and fourth sentences restate the dispatch idea already covered by 'compatibility dispatcher' and add mild 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 nine-branch dispatcher with nested payloads and no output schema, the description is adequate but thin: it never explains how to choose among the operations, deferring entirely to the siblings. Acceptable for a compatibility shim, but it leaves the per-operation semantics entirely to the schema branches.

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

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

Schema description coverage is 100%, and the nested payload fields (idempotencyKey, expectedVersion, details) carry their own documentation, so the baseline is 3. The description only says 'select operation and its matching payload', adding no semantics beyond what the schema constrains.

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

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

States a specific verb+resource (context write operations) and enumerates the nine supported operations, which distinguishes it from context_read. However, the framing as a 'compatibility dispatcher' is meta rather than describing what any single invocation actually accomplishes, so the agent learns the surface area but not the intent of each route.

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

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

Explicitly says 'prefer the individually named tool when available', which routes the agent to the nine siblings and implies this tool is a fallback. That is clear context, though it never states the positive condition under which this dispatcher is actually the right choice beyond 'named tool unavailable'.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is conveyed structurally. The description adds only the vague phrase 'privacy-filtered project metadata' and says nothing about what is mutated, whether prior state is lost, or how conflicts surface, leaving behavioral gaps despite the annotation 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?

A single short sentence with no redundancy, which is structurally clean. But it is arguably under-specified rather than concise, and the sentence does not front-load the critical action semantics an agent needs.

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

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

This is a destructive, idempotent mutation with 8 parameters, 6 required, and no output schema. The description is far too thin for that complexity, omitting what the tool operates on, the effect of each action, and the version/idempotency contract the schema implies.

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 75%, so most parameters are documented in the schema itself; the description adds no parameter-level detail (e.g., the action enum semantics or expectedVersion conflict behavior). With the remaining undocumented parameters and no compensating description text, it falls below the baseline of 3.

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

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

Names a verb ('Update') and a resource ('hosted control instruction task'), which is enough to identify the operation type. However, it does not differentiate itself from closely related siblings such as acknowledge_instruction_control, queue_instruction_tasks, or submit_node_instruction, so an agent cannot tell which one applies without opening 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?

There is no when-to-use statement, no prerequisites, and no pointer to alternatives. The only hint is 'privacy-filtered project metadata', which does not tell the agent when this tool is the right choice over the instruction-task siblings.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only "privacy-filtered project metadata," which hints at what data may be supplied but says nothing about the actual conversion behavior, whether it is reversible, or what happens on a version conflict.

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?

It is a single short sentence with no padding, which is good, but it is under-specified rather than genuinely concise — the words "hosted convert" consume the limited space without resolving the core ambiguity.

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 7-parameter mutation with a nested object, required idempotency and versioning fields, and no output schema, one sentence is inadequate. Nothing explains the conversion semantics, retry/conflict expectations, or the effect on the target note.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema documents all 7 parameters including idempotencyKey and expectedVersion. The description adds no parameter-level meaning beyond the vague reference to "privacy-filtered project metadata," which loosely maps to the nested details object but conveys nothing new.

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?

It names a verb (update) and a resource (context note), but the qualifier "convert" is never defined, so an agent cannot tell what is actually being converted or how this differs from the sibling update_context_note. The phrase "hosted convert context note" reads as a name restatement rather than a clear statement of purpose.

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

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

There is no indication of when to use this tool versus update_context_note, archive_context_note, or move_context_note, all of which operate on the same resource. No prerequisites, no exclusions, no alternative named.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds only "privacy-filtered project metadata," which hints at data handling but says nothing about what the handoff becomes, whether it replaces an existing handoff, what happens on a duplicate idempotency key, or what is returned. For a mutation with a nested payload this is thin.

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

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

It is a single short sentence with no padding, which is the right size. However, the front-loaded clause is garbled ("Update hosted create chat handoff"), so the brevity comes at the cost of comprehension rather than from efficient wording.

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

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

This is a six-parameter write operation with a nested details object, required idempotency key, and no output schema; the description explains none of the object's purpose, lifecycle, or result. Annotations cover part of the safety profile, but the core semantics of creating a handoff are absent.

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

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

Schema description coverage is 100% and idempotency/retry semantics are documented on idempotencyKey, so the schema carries the load and a baseline 3 applies. The description contributes no additional parameter meaning beyond the vague phrase about project metadata.

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?

"Update hosted create chat handoff" is internally contradictory — the name says create, the description says update — and it never states what a "chat handoff" actually is or what is being transferred. The only added phrase, "privacy-filtered project metadata," restates a property of the payload rather than the operation. It reads as a near-tautology of the tool name.

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

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

No when-to-use guidance, no prerequisites, and no mention of the obvious sibling record_chat_handoff_delivery or any other tool in the handoff family. An agent cannot tell from this text when creating a handoff is the right call versus recording a delivery or opening a session.

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

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

Annotations already declare this is a write (readOnlyHint=false), non-destructive, idempotent, and closed-world, so the safety profile is covered. The description adds only the vague phrase "privacy-filtered project metadata" and does not explain the retry/idempotency behavior that the idempotencyKey parameter implies, nor what happens on conflict or what data is persisted.

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?

It is a single sentence, but it is poorly front-loaded and self-contradictory ("Update hosted create finding"), which forces the reader to parse twice. Brevity here reflects under-specification rather than effective conciseness.

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

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

For a five-parameter mutation tool with a nested object, required idempotency key, and no output schema, one ambiguous sentence is inadequate. Nothing explains the create-vs-update semantics, idempotency behavior, or how the nested details object is used, leaving the agent under-informed about a write 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?

Schema description coverage is 100%, so the baseline is 3; the schema already documents projectId, sessionId, executionId, idempotencyKey, and the nested details fields in detail. The description adds no parameter meaning beyond that—"privacy-filtered project metadata" does not clarify any of the five 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 opens with "Update hosted create finding," which mixes the verbs update and create and directly conflicts with the tool name create_finding. "Hosted" and "privacy-filtered project metadata" are undefined jargon, so an agent cannot confidently tell this apart from its sibling update_finding. It essentially restates the name with a contradictory verb rather than stating a specific verb+resource.

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

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

No guidance is given on when to use create_finding versus update_finding, promote_insight_to_finding, or list_findings, despite those siblings existing in the same namespace. The sentence provides no context or exclusions, leaving the choice entirely to inference.

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

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

Annotations already declare the mutation/idempotency/safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful context beyond them: the write is delegated to a local agent and the server persists only 'bounded metadata and an attested outcome', which tells the agent about data retention scope. It could still say more about failure/timeout behavior on the agent round-trip.

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

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

A single dense sentence with no filler; the core action is front-loaded. The trailing clause about storage is compact and informative, though the sentence is a touch information-packed.

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 mutating tool with no output schema and a six-parameter nested schema, the description covers storage semantics but omits the local-agent prerequisite, the meaning of auxiliary IDs, and any error/failure behavior. Annotations carry the safety profile, so this is adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description offers no additional parameter meaning (no mention of idempotencyKey reuse, projectId provenance, or the bounded nested metadata). Note the schema's own descriptions are partly copy-pasted and misleading for reviewId/sessionId/executionId/status, but the description does nothing to compensate.

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

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

States a specific verb+resource ('create local change review') and adds a distinguishing detail — that the action is delegated to a connected local agent rather than handled purely server-side. It does not name the close siblings (get_change_review, list_change_reviews, refresh_local_change_review), so the differentiation is implied by the verb rather than explicit.

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

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

The phrase 'connected local agent' hints at a prerequisite (a local agent must be connected), but the description never states when to use this tool versus refresh_local_change_review, get_change_review, or list_change_reviews, nor any conditions/exclusions. Guidance is at best implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered structurally. The only behavioral context the description adds is the phrase 'privacy-filtered project metadata', which is a vague hint at filtering but says nothing about versioning (expectedVersion), idempotency key reuse, or the replacement flow implied by 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?

It is a single short sentence, which would normally be a strength, but the sentence is incoherent ('Update hosted create presentation request') and therefore wastes its brevity. Brevity without clarity is under-specification, not conciseness.

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

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

This is a 12-parameter mutation with a nested object, an anyOf requirement, an idempotency key, and a versioned replacement context, and there is no output schema. An eleven-word sentence that contradicts its own tool name is completely inadequate to explain how to invoke this correctly.

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

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

Schema description coverage is 67%, below the 80% baseline, so the description should compensate but does not. 'Privacy-filtered project metadata' loosely gestures at the nested 'details' object (summary/status/referenceIds) but adds no meaning for the required topic, description, projectId, idempotencyKey, or the scopeNodeId/replacementContext alternatives defined in the anyOf.

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's verb ('Update') directly conflicts with the tool name ('create'), and 'hosted create presentation request' merely restates the name rather than describing a specific action. With four closely-named siblings (publish_presentation_request, fail_presentation_request, retry_presentation_request, get_pending_presentation_requests), the description does nothing to distinguish this tool from 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?

There is no when-to-use guidance, no when-not-to-use, and no mention of any alternative tool. The agent is left to guess whether this creates, updates, or replaces a request, and cannot tell it apart from the create/publish/fail/retry siblings.

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

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

Annotations already declare the mutation/idempotency/safety profile (readOnly=false, idempotent=true, destructive=false), so that burden is lifted. The description adds genuine context beyond the annotations: the operation only creates a catalog record and deliberately does not publish a graph or create a repository, and it discloses the return payload since no output schema exists.

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, front-loaded sentences with zero filler: the action and its scope limit come first, the routing advice second, the return value last. Every sentence carries information an agent needs.

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?

It covers returns and operation scope, which matters given no output schema, but with four required parameters at 25% schema coverage the description leaves the parameter contract largely unexplained. Adequate for routing, incomplete 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 only 25% (only idempotencyKey is annotated), so the description is expected to compensate for displayName, projectType, and types. It never mentions any of the four parameters, leaving an agent to guess at their meaning from name and JSON-Schema constraints 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?

States a specific verb+resource (create an owned project catalog record) and immediately bounds the scope by naming what it does NOT do: no graph publish, no repository creation. It also distinguishes itself from the sibling map_project, so an agent can route without opening 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?

Explicitly tells the agent to prefer map_project when beginning a mapping, and frames this tool as a compatibility alias, which is exactly the when-to-use/when-not distinction needed. The scope exclusions (no publishing, no repo) reinforce where this tool stops.

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

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

Annotations already declare the safety profile (not read-only, idempotent, not destructive, closed-world), so the burden is lower. The description adds two genuinely behavioral facts: paragraph preservation in the prose body and a content restriction against secrets/source dumps. It does not explain what publishing produces or how the idempotency key interacts with retries.

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, no filler, with the core action front-loaded and the content constraints following. Every sentence carries information; it could be tighter only by merging the last two clauses.

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

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

This is a complex mutation (9 parameters, nested objects) with no output schema, so the description should carry more weight. It omits any mention of the optional scoped 'outcome' object, attachments, or retry semantics, leaving an agent to discover the tool's richer capabilities from the schema alone. Adequate but with clear gaps.

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

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

Schema coverage is 56%, so the schema documents some parameters (projectId, idempotencyKey, sessionId, executionId) but the description only names title, summary, and body. It adds no meaning beyond those three field names and leaves the complex nested 'outcome' scope/criteria/evidence structure entirely to the schema. This compensates only partially for the coverage gap.

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: 'Publish an authored narrative report to Reports.' The phrase 'authored narrative report' distinguishes it from read/write siblings like get_report, list_reports, and update_report, though it never explicitly names any alternative. Clear purpose, but sibling differentiation is left implicit.

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 content guidance ('Provide a distinct title, summary, and prose body', 'Exclude secrets and source dumps') but never states when to use this versus alternatives such as queue_report, create_report_bug, or update_report. The usage context is implied rather than explicit, and no prerequisites or exclusions are given.

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

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

Annotations already declare write (readOnlyHint=false), non-destructive, idempotent, and closed-world. The description adds little beyond repeating fields: no mention of permission requirements, what happens on duplicate idempotency, or what the returned identifier looks like. With annotations covering safety, a 3 is fair but not more.

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, front-loaded with the action and resource, no filler. Every clause carries information.

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

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

A 9-parameter mutation with no output schema and partial schema coverage. The description covers the primary required fields and the optional link, but leaves sessionId/executionId unexplained and doesn't describe the result (new finding ID?). Adequate but clearly incomplete.

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

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

Schema coverage is 56%, so some parameters are documented only in the schema (reportId, projectId, sessionId, executionId, idempotencyKey all have descriptions). The description lists title, notes, severity, linkedNodeIds, but doesn't clarify the semantics of sessionId, executionId, or the severity enum levels. It mildly compensates for the coverage gap.

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 ('Open') and resource ('canonical finding in Reports'), and names optional linkage to reportId. It's distinguishable from create_finding and queue_report_bug, though the 'canonical finding' jargon leans slightly toward internal terminology.

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

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

No guidance on when to use this vs. siblings like create_finding, queue_report_bug, or queue_report. The 'optionally linked to reportId' hint suggests a relation to an existing report but doesn't state when that path applies.

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

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

Annotations already declare it a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds only the 'privacy-filtered project metadata' qualifier about the payload; it says nothing about required permissions, the effect of the update, or what happens to existing panels. With annotations present, this modest added context lands at 3.

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

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

A single front-loaded sentence with no padding or redundancy, which is appropriate sizing. It is however dense with domain jargon ('curate scope panels') that slightly reduces immediate comprehensibility.

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

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

For a mutation tool with five parameters, a nested object, and no output schema, one sentence is insufficient: it never explains what curate scope panels are, when the tool should be used, or the expected effect. Annotations cover idempotency but cannot substitute for this operational context.

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

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

Schema description coverage is 100%, so the schema already documents projectId, idempotencyKey, and the bounded 'details' object. The description only gestures at 'privacy-filtered project metadata' without clarifying the details fields or the optional sessionId/executionId semantics, so it does not exceed the baseline.

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

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

The description has a definite verb ('Update') and resource ('hosted curate scope panels') plus a data-qualifier ('privacy-filtered project metadata'), so the agent can grasp what the tool does. It does not, however, distinguish this tool from siblings like scope_write, claim_map_scope, or release_map_scope, which also touch scope state.

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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The agent is left to infer from the name alone whether this supersedes scope_write or the map-scope tools; nothing in the text routes 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds real value beyond them: it discloses that the call returns a versioned deletion result and explicitly enumerates what is NOT destroyed (project, source files, session). That blast-radius statement is the kind of context annotations cannot express.

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, zero filler, and the purpose is front-loaded before the scope-limiting clause. 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 destructive, version-guarded mutation with seven parameters and no output schema, the description covers the essential points: identity of the target, the returned result, and the nonexistent side effects. It leaves the roles of the optional details/sessionId/executionId fields unexplained, but those are secondary to calling 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 description coverage is nominally 100%, so the schema carries the parameter burden and baseline 3 applies, though several schema descriptions are copy-pasted project-ID text on noteId/sessionId/executionId, which muddies them. The description at least names noteId and expectedVersion as the operative identifying pair, but adds no format or conflict-handling detail beyond what the schema already says.

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 (delete a Context note) and preemptively bounds the blast radius — it will not delete the project, source files, or session. It stops short of differentiating from the closest sibling, archive_context_note, which an agent must also consider.

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 this applies (removing a single owned note) and scopes what it does not affect, but never says when to prefer delete over archive_context_note or convert_context_note, nor states any preconditions beyond the implicit version requirement.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by clarifying what is actually destroyed (the finding record, not a code defect), which prevents a common misuse. It does not add rate limits, auth requirements, or conflict-retry 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 sentences, front-loaded with the operation and required identifiers, followed by the semantic distinction and the alternative. No filler, 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 destructive mutation with four required parameters, the annotations cover safety and the schema covers parameter mechanics, so the description only needs purpose, target semantics, and routing – all present. Only the response/conflict outcome and any dependent-data effects are left unaddressed, and there is no output schema to compensate.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit: the schema's own description for findingId is copy-pasted from projectId ('Owned project ID returned by list_linked_projects'), which is misleading, and the description correctly establishes findingId as the finding identifier while tying expectedVersion to the delete operation.

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 (delete) and a precisely scoped resource (one owned finding), and immediately disambiguates the target from source-code defects. An agent can distinguish it from create_finding, update_finding, and list_findings without opening any schema.

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

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

Names the alternative explicitly ('use update_finding to record a resolution instead'), giving a clear when-not-this-tool rule. It stops short of stating prerequisites such as ownership requirements or the need to re-read before retrying after a version conflict, which the agent must infer.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that by pinning the blast radius: it removes the stored investigation record specifically, not project graph nodes or local files. It still says nothing about whether the delete is recoverable, what happens to linked findings, or required 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, front-loaded with the action and the two key identifiers, followed immediately by the scope limitation. Every clause earns its place and there is 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 destructive, version-guarded mutation with seven parameters, no output schema, and no annotations explaining conflict behavior, the description covers the resource scope adequately but omits recoverability, the effect on related records, and the retry/version-conflict workflow (left to the schema). An agent can call it correctly, but with some inference.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including idempotencyKey retry semantics and expectedVersion conflict behavior. The description only names investigationId and expectedVersion without adding format, ownership, or conflict-handling detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (delete) and resource (one saved investigation), plus a negative scope boundary ('not project graph nodes or local files') that separates it from graph-mutating siblings like clear_project_graph or patch_project_graph. It does not name a sibling alternative (e.g. delete_finding), but the scope 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?

Usage is implied by the verb and the boundary statement, which tells the agent this is not the tool for removing graph nodes or local files. There is no explicit when-to-use/when-not guidance, no mention of prerequisites such as reading the record first for expectedVersion, and no routing to delete_finding or delete_context_note for adjacent resources.

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

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

Annotations already declare destructive=true, idempotent=true, openWorld=false, so the safety profile is partly covered. The description adds real context beyond them: only terminal entries are eligible, and the operation neither executes nor cancels active tasks. It stops short of stating irreversibility, batch limits, or what a version mismatch does.

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, with the core action front-loaded and the disambiguation clause following. 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 destructive 5-parameter tool with no output schema and rich annotations, the description covers purpose, scope, and routing adequately. It leaves unstated what happens on a stale expectedVersion and the significance of the idempotencyKey for retries, though the schema covers the latter.

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%, so the schema carries most parameter documentation. The description's 'recorded IDs and versions' loosely maps to queueItemId/expectedVersion and hints at optimistic concurrency, but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (delete) and a precisely scoped resource (terminal queue-history entries) rather than generic 'delete'. The second sentence explicitly separates it from cancel_queue_item, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives an explicit when-not ('this tool does not execute or cancel an active task') and names the correct alternative (cancel_queue_item) for active work. Routing is unambiguous.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context by noting that project metadata is privacy-filtered, but it does not describe what the returned capability data looks like or any other behavioral characteristics.

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

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

A single front-loaded sentence with no filler or repetition. Every phrase ('hosted', 'privacy-filtered project metadata') adds a piece of context, keeping the definition compact.

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, annotation-rich tool, this is nearly sufficient. The gap is the absence of a concrete statement about what the returned capabilities represent, especially since there is no output schema to fill that in.

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 zero parameters and an empty schema, there is no parameter documentation burden on the description. The mention of 'privacy-filtered project metadata' hints at ambient context, which is enough for a parameterless call.

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

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

The description states a specific action ('Read') and resource ('hosted describe capabilities'), so it is not a tautology. However, 'hosted' and 'capabilities' are left somewhat vague, and the description does not clarify what kind of capabilities are returned or how this differs from sibling read tools.

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

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

Usage is implied by the name and description: an agent would call this to obtain capability descriptions. There is no explicit when-to-use guidance, no exclusions, and no alternative tools mentioned, so the agent must infer appropriateness from context.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description usefully adds that results are complete and in canonical node order (deterministic ordering matters for diffing), but says nothing about whether it reflects the last published version, how pagination interacts with that completeness claim, or any auth/scope constraints.

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

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

One sentence, front-loaded with the action and resource, then the distinguishing property, then the use cases. No filler and nothing structural to fix.

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

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

With no output schema, the description carries the burden of describing return content, and it only does so loosely ('the published graph... in canonical node order'). Given a 4-parameter paginated read against a dense graph tool surface, a note on pagination semantics or the distinction between published vs. working graph would round this out.

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

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

Schema description coverage is 100% and each parameter is documented in-schema (cursor, pageSize, projectId, sessionId), so the description need not explain them. It adds no parameter-level meaning of its own, which is the expected baseline here.

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

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

States a specific verb and resource (read the published graph back), and adds a distinguishing trait (complete, canonical node order) that separates it from nearby readers like graph_read, get_context_graph, and get_graph_scope. It stops short of naming any sibling explicitly, so an agent still has to infer which reader it wants.

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 lists intended purposes (diffing, resuming, verifying a mapping), which implies the usage context, but never says when NOT to use it or which sibling reader is the alternative for other needs. That leaves a crowded field of graph readers (graph_read, get_context_graph, get_graph_wiki) without routing 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?

Annotations already declare this is a non-read-only, non-destructive, idempotent, closed-world mutation, so the safety profile is covered. The description adds only the "privacy-filtered project metadata" hint about the details payload, and says nothing about auth needs, what failing a request does downstream, or side effects. No contradiction with annotations.

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

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

A single sentence, front-loaded with the verb and resource, with no padding or redundancy. It is efficient, though its brevity comes at the cost of clarity rather than wasted words.

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

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

For a mutation tool with 8 parameters, a nested object, and no output schema, one vague sentence is not enough. It never explains what "fail" does to the request, what the resulting state is, or how it interacts with the request lifecycle, leaving the agent to reconstruct intent from the schema alone.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including the nested details object and idempotency/versioning semantics. The description's "privacy-filtered project metadata" loosely gestures at details but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a verb ("Update") and a resource ("fail presentation request"), but the name/verb mismatch ("fail" vs "update") and the opaque phrase "privacy-filtered project metadata" leave the actual action ambiguous. It does not distinguish this from close siblings such as retry_presentation_request, create_presentation_request, or publish_presentation_request.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives even though retry_presentation_request is an obvious sibling for the opposite action. The agent must infer the lifecycle context entirely.

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

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

Annotations already declare that this is a mutating, idempotent, non-destructive, closed-world operation. The description adds only 'privacy-filtered project metadata,' which does not clarify what gets changed, what must already exist, whether retries are safe beyond the idempotencyKey hint, or what the caller should expect after finalization.

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 short sentence with no wasted words, so it is structurally concise. However, its terseness leaves it under-specified rather than appropriately concise for a six-parameter mutation 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?

For a complex mutating tool with five required parameters, a nested changedProjects array, no output schema, and no sibling differentiation, the description is far too thin. It omits operational meaning, usage context, parameter semantics, and behavioral details that an agent needs to invoke it correctly.

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

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

Schema description coverage is only 33% across six parameters, and the description does not compensate. It does not explain terminalStatus values, occurredAt, changedProjects structure, summary constraints, or how executionId relates to begin_agent_execution; the phrase 'privacy-filtered project metadata' is too vague to add parameter meaning.

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 restates the tool name with 'Update hosted finalize agent execution' and adds only a vague modifier about using privacy-filtered project metadata. It does not state what finalizing means operationally, such as setting a terminal status or recording changed projects, and it does not distinguish this tool from siblings like begin_agent_execution or record_agent_execution_activity.

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?

There is no guidance on when or when not to use this tool. It does not mention prerequisites, alternatives such as begin_agent_execution or get_agent_execution_status, or the conditions that should select this mutation over other execution-related 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?

Annotations already declare this is a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds only the vague clause 'privacy-filtered project metadata' and says nothing about what the session record becomes after finishing, whether prior data is preserved, or the effect of the version conflict implied by expectedVersion.

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?

It is a single short sentence with no padding, which is structurally clean. However the wording is awkward ('Update hosted finish agent session') and front-loads nothing an agent needs, so brevity comes at the cost of usefulness rather than serving it.

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

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

This is a complex mutation with 10 parameters, 6 required, a nested codeChanges object, no output schema, and no annotation coverage of outcome semantics. A one-line description that merely echoes the name leaves the agent without the information needed to invoke it correctly.

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

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

Schema description coverage is only 50%, yet the description explains none of the 10 parameters, including the required codeChanges array and its completion-declaration semantics, idempotencyKey, or expectedVersion. The only informal mapping is 'project metadata' to projectId/summary, which the schema already handles better.

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 'Update hosted finish agent session using privacy-filtered project metadata' largely restates the tool name rather than stating the action it performs (finalizing an agent session with a summary and code-change declaration). It never distinguishes itself from siblings like start_agent_session, finalize_agent_execution, or begin_agent_execution, so the agent learns nothing new about what this tool actually does.

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?

There is no when-to-use guidance, no statement of prerequisites (e.g. that it closes a session opened by start_agent_session), and no reference to alternatives such as finalize_agent_execution. The phrase 'privacy-filtered project metadata' hints at a constraint but never explains what it implies for the caller.

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

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

Annotations already declare the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description still adds real context beyond them: it discloses that the operation is delegated to a local agent and that the server persists only bounded metadata plus an attested outcome, which explains why details is field-restricted.

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

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

A single front-loaded sentence with the action first and the storage caveat second; every clause carries information. The compressed storage clause is slightly dense but not wasteful.

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

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

For a required-param mutation with a nested object, an idempotency key, optimistic-concurrency versioning, and no output schema, the description covers the delegation model but omits what a successful finish changes, what happens if no local agent is connected, and how version conflicts surface.

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 itself documents nodeId, projectId, idempotencyKey, expectedVersion and the details object. The description's 'bounded metadata' phrase loosely reinforces the details constraint but adds no semantics beyond the schema, so baseline 3 applies.

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

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

States a concrete verb+resource (finish node work) and names the actor it targets (the connected local agent). It is distinguishable from siblings like start_node_work and finish_agent_session by the 'node work' scope, though it never names an alternative explicitly.

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

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

Usage is only implied by the name pairing with start_node_work; there is no statement of when to call this versus finish_agent_session, finalize_agent_execution, or an abort path, and no precondition such as an active execution or connected agent being required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds one genuine piece of context beyond that — results are drawn from privacy-filtered project metadata — but says nothing about freshness, polling behavior, or what states an execution can be in.

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?

It is a single short sentence, which is appropriately sized, but the wording 'Read hosted get ...' is redundant and awkward rather than economical. Brevity here comes partly from under-specification, not tight authoring.

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 read tool with a fully documented schema and complete annotations, the description is minimally adequate. It lacks any statement of what the returned status represents or when the call is appropriate, and no output schema exists to fill that gap.

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

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

Schema description coverage is 100% and the single executionId parameter is already documented thoroughly, including the disambiguation 'not a session or project ID'. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

The description does convey the resource (agent execution status) and an action (read), so an agent can guess the intent. But the phrasing 'Read hosted get agent execution status' is garbled and tautological, and it never distinguishes this tool from close siblings such as begin_agent_execution, finalize_agent_execution, record_agent_execution_activity, or get_project_status.

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

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

There is no when-to-use guidance, no prerequisite (e.g. that an execution must have been started via begin_agent_execution), and no mention of alternative tools for adjacent needs. The only hint is the param note in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The only added signal is 'privacy-filtered project metadata', which hints at a data-trimming behavior but is too vague to disclose what is filtered or what the response contains.

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?

It is a single sentence, so it is short, but 'Read hosted get change review' is awkward and wastes its opening on redundant/ungrammatical phrasing instead of front-loading the actual 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 read tool with annotations, no output schema, and four parameters, the description should at minimum say what a change review is, how a reviewId is obtained, and how it differs from the list sibling. None of that is present, leaving the agent under-informed.

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 nominally 100%, but all four parameters (reviewId, projectId, sessionId, executionId) carry the identical copy-pasted description 'Owned project ID returned by list_linked_projects', which is factually wrong for reviewId/sessionId/executionId. The description adds nothing about parameters, so it fails to compensate for that misleading schema text.

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 phrase 'get change review' names a recognizable verb+resource, but the surrounding text ('Read hosted ... using privacy-filtered project metadata') is garbled filler that muddles rather than sharpens the purpose. It gives no differentiation from close siblings like list_change_reviews or create_local_change_review, which an agent must choose between.

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?

There is no statement of when to use this tool versus list_change_reviews, refresh_local_change_review, or any other review-related sibling. The agent gets no trigger conditions or prerequisites (e.g., that a reviewId first comes from list_change_reviews).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that these are 'recorded' nodes scoped to an owned project, which is modest added context, but says nothing about pagination, result size, or ordering.

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 tightly packed sentences with the purpose first and the disambiguation second. No filler, no repetition of the name.

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

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

There is no output schema, but annotations cover the safety profile and the description sketches the return shape (nodes and links). However, it ignores the optional sessionId/executionId filters entirely, leaving the agent to infer their effect from a schema whose descriptions for those two fields are erroneous.

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 carries parameter documentation and the baseline is 3. The description adds no meaning about projectId, sessionId, or executionId — notably it doesn't clarify that sessionId/executionId narrow the read, which matters given the schema's copy-paste descriptions for those fields.

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 (Read) and resource (recorded Context nodes and their links) and scopes it to an owned project. It also explicitly distinguishes itself from the sibling get_graph_scope, so an agent can route without inspecting either schema.

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

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

Gives both when to use it ('session reasoning and decisions') and when not to ('not the structural project graph'), naming the alternative tool get_graph_scope explicitly. This is exactly the routing signal an agent needs.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context beyond them: 'This reads recorded context, not current local source,' which tells the agent the data may be stale relative to disk. It does not cover scope or pagination of the returned overview.

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, zero filler, and the caveat about recorded vs. local source is front-loaded right after the action statement. 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 read-only tool whose annotations already carry the safety profile and with no output schema to explain, the definition covers what is read and a key data-freshness caveat. The remaining gap is the unexplained sessionId/executionId scoping parameters, whose schema text is erroneous.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds nothing about projectId/sessionId/executionId semantics. Worse, the schema's own descriptions for sessionId and executionId are copy-pasted from projectId ('Owned project ID returned by list_linked_projects...'), so the description misses a chance to disambiguate what those two optional scoping parameters actually narrow.

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 gives a specific verb and resource ('Read the Context overview for an owned project') and implicitly contrasts it with the 'detailed context graph', which separates it from get_context_graph. It falls short of naming that sibling outright, so the differentiation is inferred rather than stated.

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?

'orient yourself before inspecting its detailed context graph' establishes a clear sequencing context: call this first at a coarse level, then drill in with get_context_graph. No explicit when-not-to-use or alternative is named, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description only adds the qualifier 'privacy-filtered project metadata', which hints at data scoping but says nothing about what the widget state contains or how it changes.

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?

It is a single short sentence with no padding, but the wording is awkward and repetitive ('hosted get dashboard widget state'), making it less front-loaded and readable than it could be.

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

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

There is no output schema, so the description could reasonably say what 'widget state' is returned, and it never relates this tool to open_dashboard_widget. Combined with annotations that cover the safety profile, this is adequate but with clear gaps.

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

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

Schema description coverage is 100% and the single projectId parameter is thoroughly documented in the schema itself (source tool, format exclusions). The description adds no parameter-level information, so baseline 3 applies.

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

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

The description names a verb (Read) and a resource (dashboard widget state), so the basic purpose is inferable, but the phrasing is garbled ('hosted get dashboard widget state') and it never distinguishes itself from the sibling open_dashboard_widget, leaving the agent to guess which one to pick.

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

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

No when-to-use, when-not-to-use, or alternative is given. With a closely named sibling (open_dashboard_widget) in the list, an explicit routing statement is exactly what is missing here.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral note is that the read is scoped to "privacy-filtered project metadata," which is a genuine but thin addition — it does not say what the status represents or what is filtered out.

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?

One sentence is appropriately short, but it is not front-loaded cleanly — "Read hosted get github app status" wastes words and obscures the action. There is no filler to cut, but the phrasing is muddled rather than efficient.

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

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

With no output schema, the description bears some burden for explaining what comes back, and "github app status" is never unpacked — an agent cannot tell whether it receives an install state, permissions, webhook health, or an auth token. Annotations cover the safety dimension, so the gap is scoped to return semantics and param relationships rather than to behavior, keeping this at a minimum-viable 3.

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 documented parameters carry their own semantics and the baseline is 3 per the rules. The description adds nothing about the relationship between projectId (required) and the optional sessionId/executionId, and notably does not correct the schema's copy-paste defect where sessionId and executionId are both described as "Owned project ID returned by list_linked_projects."

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 phrase "get github app status" names a verb and resource, but it is wrapped in a garbled construction ("Read hosted get github app status") that reads as a stitched-together pipeline fragment rather than a clear statement of purpose. It does not distinguish this tool from the many other status readers in the sibling list (get_project_status, get_agent_execution_status, get_project_sync_status).

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

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

The description gives no guidance on when to use this tool, when not to, or which sibling to prefer. With roughly a dozen status/read tools available, the absence of any routing guidance leaves selection entirely to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral boundaries beyond that: pagination behavior and the explicit negative scope ("Does not read Context session history"), which the annotations and schema do not convey.

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

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

Three short sentences, front-loaded with the core action, followed by the entry rule and the exclusion. No filler, and each sentence carries distinct information.

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

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

For a read-only tool with a 100% documented schema and annotations covering safety, the description is sufficient to call it correctly. It is slightly thin on what "scope and relationships" actually returns, but with no output schema and a clear sibling pointer, this is a minor gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (cursor, pageSize, nodeId, projectId, etc.). The description only repeats "Supply nodeId" and adds no syntax, format, or constraint detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource ("Read a selected published graph node's scope and relationships") plus a scoping detail (pagination). It also carves out a boundary against context/session tools with "Does not read Context session history." It does not explicitly distinguish itself from close siblings like graph_read or scope_read, so it stops short of a 5.

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

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

Gives explicit entry guidance ("Supply nodeId; use get_roots first when you do not know a starting node") and one exclusion ("Does not read Context session history"). This is clear context plus a named alternative, but it lacks a full when-to-use-vs-when-not decision against other graph readers.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description contributes one extra behavioral fact — that results are privacy-filtered — which is genuinely useful (some content may be redacted), but it says nothing about return shape or size limits.

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?

It is a single sentence, but the sentence is malformed ("Read hosted get graph wiki") and conveys almost no actionable information, so brevity here is under-specification rather than economy.

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 tool with no output schema, the description should at least say what the wiki entry contains and how it relates to the published graph. Annotations cover the safety profile, but the purpose and return content remain opaque, and the garbled wording leaves the agent guessing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds nothing about the parameters, and it cannot compensate for the schema's own defect that sessionId and executionId carry copy-pasted descriptions referring to a project ID.

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

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

The phrase "Read hosted get graph wiki" just restates the tool name in garbled form rather than describing the resource or what is returned. "Using privacy-filtered project metadata" adds a hint of scope but the agent still cannot tell what a "graph wiki" is or how it differs from siblings like knowledge_read, graph_read, or request_node_explanation.

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

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

No when-to-use guidance and no named alternative, even though the schema itself points at get_roots and get_graph_scope for node discovery. The agent gets no indication of when this read is preferable to the many other read tools in the sibling 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description's only added behavioral detail is 'privacy-filtered project metadata,' which hints at filtering but does not explain what is filtered, auth requirements, or response 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?

It is a single short sentence, but the phrasing 'Read hosted get ownership' is awkward and not front-loaded with a clear action+resource. The sentence does not earn its place because it fails to convey actionable meaning.

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

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

With no output schema, an agent needs the description to explain what ownership data is returned and how privacy filtering affects it. The description does none of this, and it adds no clarification for the three parameters despite malformed schema descriptions.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the schema descriptions for sessionId and executionId are erroneous copies of the projectId description, and the tool description does nothing to clarify any of the three 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 restates the tool name ('get ownership') and adds only a vague qualifier ('using privacy-filtered project metadata'), without defining what ownership is (project? user? code?) or distinguishing it from sibling getters like get_project_health or get_graph_scope. This is close to a tautology.

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

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

No when-to-use guidance or alternatives are provided. It does not indicate when to call get_ownership versus list_linked_projects, map_project, or other get_* 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The only added context is 'privacy-filtered project metadata', which is a thin hint and does nothing to describe pagination behavior, filtering semantics, or result characteristics beyond the annotation.

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?

It is a single short sentence with no padding, which is good, but the phrasing ('Read hosted get pending implementation meter changes') is awkward and largely redundant, so brevity here reflects under-specification rather than disciplined conciseness.

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

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

For a four-parameter, paginated read tool with no output schema, the description says nothing about what a pending meter change is, how pagination works, or what callers receive. The safety-relevant behavior is covered by annotations, leaving the description too thin 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 75%, so the schema already documents cursor and projectId (sessionId's text is a copied-over projectId description). The description adds no additional meaning about limit, cursor, or scope, so the baseline of 3 is appropriate.

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

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

The description restates the tool name almost verbatim ('Read ... get pending implementation meter changes'), which is tautological rather than an independent statement of purpose. It gives no differentiation from siblings like apply_implementation_meter_change or queue_implementation_meter_request, so an agent cannot easily tell which to pick.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The agent gets no signal on when this read is appropriate versus queue/apply operations on the same meter-change resource.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's only added behavioral claim is 'privacy-filtered project metadata', which hints at access scoping but is not explained (what is filtered out, or on what authority). Modest added value against a low annotation bar.

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?

It is a single short sentence, so there is no padding, but 'Read hosted get' is noise that muddies the verb rather than front-loading the action. The one substantive clause, 'privacy-filtered project metadata', arrives after the garbled prefix.

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?

Five parameters (four optional filters), no output schema, and no explanation of which optional IDs narrow the result set or how they interact. With the schema descriptions effectively broken by duplication, the description was the only place to compensate and it does not, so an agent cannot confidently build a filtered 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?

Schema description coverage is 100%, so the baseline is 3. The description adds nothing about how projectId, requestId, sessionId, executionId, or presentationId scope the query, and the schema's own descriptions are identical boilerplate ('Owned project ID returned by list_linked_projects...') for all five properties, so neither layer clarifies what each filter does.

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 phrase 'get pending presentation requests' does state a resource and read intent, but it is buried in garbled templated wording ('Read hosted get pending presentation requests'), which reads like a string-substitution artifact. It does not distinguish this tool from close siblings such as get_pending_implementation_meter_changes, get_pending_scope_organizations, or list_presentations.

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

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

No when-to-use condition, no prerequisites, and no named alternative. An agent cannot tell from this description when a pending-request lookup is the right call versus list_presentations or get_presentation. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds one behavioral hint — "privacy-filtered project metadata" — indicating results are filtered for privacy, which is genuinely beyond the annotations, though it is vague about what exactly is filtered.

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?

It is a single short sentence, but conciseness is only valuable when the sentence earns its place. Here the one sentence just echoes the name and appends a vague qualifier, so brevity reflects under-specification rather than discipline.

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

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

With no output schema and an ambiguous resource ("pending scope organizations"), the description should explain what the tool returns and what "pending" means. It provides neither, leaving the agent unable to predict the result of the 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?

Schema description coverage is 100%, so the baseline is 3, but the schema descriptions for sessionId and executionId are copy-pasted from projectId (all three read "Owned project ID returned by list_linked_projects"), which is misleading. The tool description adds nothing to clarify what sessionId or executionId actually mean, so it fails to compensate for the schema's 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?

"Read hosted get pending scope organizations" essentially restates the tool name verbatim, so the sentence is a tautology rather than an explanation of what a "pending scope organization" is or what operation is performed on it. Nothing distinguishes it from closely named siblings like get_pending_presentation_requests or get_pending_implementation_meter_changes.

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

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

No when-to-use guidance is present. The description does not say when an agent should call this instead of the many other read/get tools, nor does it name any alternative or prerequisite (e.g., that a projectId must first come from list_linked_projects).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds one useful behavioral detail — output is privacy-filtered project metadata — but says nothing about permissions, error behavior, or filtering rules.

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?

It is a single short sentence with the verb front-loaded, so there is no padding. However, the awkward construction "Read hosted get presentation" hurts readability rather than adding value.

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

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

With 5 parameters, no output schema, and a read operation over hosted presentations, the description should say at minimum what is returned and how it differs from sibling read tools. Neither is present, leaving the definition inadequate 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%, so the baseline is 3, and the description contributes no additional parameter meaning. Notably the schema descriptions are copy-pasted boilerplate (every field, including presentationId, is described as a project ID), which the description does nothing to clarify.

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