Maplith

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses a substantial behavioural rule set: 'Needs: a key that may act', the distinction between an autonomous key that 'sees the whole map' and an admin's delegate key that 'answers as the admin', and which kinds are withheld for person confirmation. It also states that 'a person's answer stands' and that suggestion confidence reflects past correctness, not certainty. What it does not disclose is what happens to the question after answering or how failures surface.

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

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

Purpose is front-loaded in the first sentence, which is good, but the remainder is a single dense paragraph joined by semicolons that interleaves per-kind definitions, evidence rules, and key-permission rules. It is information-rich but hard to scan, and the critical permission rules are buried at the end where they are easy to miss.

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, multi-mode tool with no output schema, the description covers the essential ground: what each kind asks for, who may answer each kind, and the evidence standard for `reason`. The remaining gap is the outcome side — nothing says whether answering closes the signal, what the agent receives back, or what happens if the answer is wrong later.

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 only marginally exceeds it: it explains conceptually what each `kind` means (e.g. grain = 'the one or two columns that identify a row, or []', auto_detected = confirming what agents' reports added), which the schema mostly restates. Guidance on `accept_suggestion`, `same_as`, and `other_table` semantics leans on the schema's own enum descriptions rather than adding new depth.

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

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

The first sentence states a specific verb and resource: answering a question that Maplith (the system) posed about the human's data, and the per-kind enumeration makes the scope of the tool unmistakable. It does not explicitly contrast itself with the sibling `ask` (the inverse direction) or explain when a question originates, so it falls just short of full sibling differentiation.

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 names, per `kind`, which pending uncertainty each answer resolves (field_identity_unsure, grain_unsure, schema_dialect_unsure, lineage_direction_unsure) and directs the agent to `get_task_context` for the exact `answer_with` call. The alternative path is also given: answer only from what was checked in the human's own systems, or 'ask your human'. What is missing is a clear statement of when not to answer at all versus delegating, but the context is otherwise explicit.

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

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

Goes far beyond the annotations: it discloses that the tool is metered against a daily allowance and per-key limited, that it is metadata-only and never reads rows or runs anything in external systems, and that it will not invent elements. It also describes return semantics the annotations cannot carry — citations are reusable ids, cited routes carry measured verified_rate, unmeasured_joins flags never-measured joins, and doc:<page> citations answer Maplith questions. No contradiction with readOnlyHint/openWorldHint=false.

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 then routing rule, and the dense middle section is all substantive disclosure rather than filler. It is long, and the trailing "Grounding fields: maplith://docs/mcp" line reads as a dangling pointer with no explained use, which keeps it below a 5.

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

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

Covers everything an agent needs for a metered, read-only Q&A tool with no output schema: what input it takes, what the answer will draw on, how citations can be chained into fetch/get_object/route, how to detect unmeasured joins, and what the tool refuses to do. No output schema exists, and the description compensates by describing the response's citation structure explicitly.

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

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

Schema coverage is 100% for the single `question` parameter, so the baseline is 3; the description earns an extra point by scoping what a question may be about ("what your key may see: objects, fields, relations and join keys, findings, a bounded page of open signals, processes, metrics and tracked values") and by advising "keep questions specific." The length cap it mentions (<1,000 characters) merely restates the schema's maxLength.

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

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

Opens with a specific verb+resource ("Ask the map one question in plain language") and immediately states the return shape ("an answer with its sources"). It distinguishes itself from five named sibling tools in the very next sentence, so an agent can tell what this does and what it is not without opening the schema.

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

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

Explicitly states when to choose this tool ("a question spans several parts of the map or you do not yet know which tool holds the answer") and names the faster direct alternative for each known case: get_object, route, get_metric, list_findings, search. The exclusion condition ("For one known thing the direct tool is faster and not metered") is stated as a rule, leaving nothing 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?

Beyond the annotations it discloses what an agent genuinely needs: retries are safe and return the same run, the operation takes minutes, a scan exceeding today's remaining budget is refused with a restart time, and scanning requires an accepted Terms/DPA and an upload-consent key. That adds real context (latency, quota refusal, auth gate) on top of the idempotentHint and destructiveHint=false already given.

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 essential routing and prerequisite information comes first, but the description is a run-on chain of clauses and the sentence about reading current connections and keeping earlier uploaded systems does not clearly earn its place. It is informative rather than padded, yet a tighter structure would improve scannability.

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 one-parameter, non-destructive, long-running scan tool with no output schema, the description covers prerequisites, latency, quota refusal, retry behavior, and the next step. The only ambiguity is what 'reads current connections and keeps earlier uploaded systems' means for the caller, which slightly undercuts an otherwise complete picture.

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 single parameter is already documented, but the description adds the retry semantics tied to that id — the same upload_id returns the same run — which is meaning the schema does not convey. The rest of the parameter story is left to the schema, which is appropriate for a one-parameter tool.

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

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

The description opens with a specific verb and resource: 'Start a scan from a submitted upload and follow its run,' and it names the sibling that produces the input (submit_sources) and the one that consumes the result (get_map_overview). That lets an agent place it in the pipeline without opening a schema. The one muddy sentence, 'It also reads current connections and keeps earlier uploaded systems,' blurs the otherwise crisp 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?

It gives an explicit sequence (call after submit_sources with its upload_id, then call get_map_overview) plus the prerequisites that would otherwise cause a silent failure: an owner/admin must accept Terms and DPA at human_action_url, and the key needs upload consent. There is no explicit 'do not use this when…' exclusion, and the scan-budget refusal is described as a behavior rather than a routing rule, so it falls 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantive context beyond them: it enumerates the full taxonomy of gaps detected, tells the agent the answer leads with one job per playbook/signal kind/operation and carries a fix link plus a suggested action, and discloses that a scoped key sees only in-scope gaps. The hourly scheduling and setup_gap signal emission are behaviors no annotation could 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?

It is well front-loaded, but the middle is a single sprawling sentence enumerating nine gap types in semicolon-delimited clauses, which is hard to scan and borders on a spec dump. 'Changes nothing' also restates readOnlyHint=true, the one sentence that does not 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?

With no parameters and no output schema, the description must carry the return shape itself, and it does: it lists what each gap contains, how the answer is ordered, and what remediation guidance accompanies it. It also covers scope restriction and the fact that the tool mutates nothing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description spends its words on output shape instead, which is the right trade for a zero-arg tool.

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

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

The first sentence states a specific verb and scope: checking whether every raised signal has a handling path, plus the repairs for each missing link. It then explicitly separates itself from list_signals ('use list_signals for the open work itself'), so an agent can choose between the two without opening either schema.

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

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

States explicit triggers ('when signals go unhandled or your human asks what is missing') and names the alternative tool with the condition that selects it. It also notes Maplith runs it hourly and raises setup_gap signals, which tells the agent when the check has already happened on its behalf.

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 declare the safety profile (not read-only, idempotent, non-destructive); the description adds the traits that actually matter here: disabled until a human opts in, aggregates-only retention, values persist after stopping, an auth requirement ('Needs: an autonomous key'), and the shape of the failure path. No contradiction with destructiveHint=false or idempotentHint=true.

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

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

Purpose and the off-by-default caveat are front-loaded, and most clauses carry real information (period vs. per-scan recording, auth, stop semantics). It runs long and mixes configuration guidance with troubleshooting in one block, but no sentence is pure 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 non-read-only config mutation with full annotation coverage and no output schema, the description covers defaults, retention, permissions, and failure handling. The only soft spot is what a successful call returns, which is gestured at ('the answer says why') rather than described, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents direction ('up' rising is bad) and threshold semantics, so the description largely restates them. It adds one genuine nuance the schema lacks: the threshold is drawn for the current figure type and must be redrawn when the formula changes shape. That extra earns a bit above floor but does not carry new meaning for name or tracked.

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

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

Opens with a precise verb triple and resource: 'Start, change or stop tracking a metric's value over time'. It also draws the boundary against the sibling it will be confused with ('get_metric hands back the series'), so the agent can pick between writing tracking config and reading values without opening either schema.

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

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

Explicit when-to-use (human must ask first; off by default), how to stop ('Pass tracked false'), when to touch the threshold ('redraw it when the formula changes shape'), and what to do on failure ('tell your human rather than wait'). The alternative for reading data is named. Nothing material is left 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?

Goes well beyond the annotations: corrections persist across later uploads, only re-home files, never remove map entries or alter object names/access/answers, are undoable at Data sources › Scans, are refused while a scan is queued or running, and cannot wait for approval. It also states the auth requirement (autonomous key that sees the whole map).

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

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

Front-loads the operations, then consequences, then constraints. Dense but each sentence carries information; the run-on sentence combining persistence, non-destructiveness, and undo is slightly overloaded.

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

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

For a 4-param mutation tool with no output schema, it covers effects, reversibility, blocking conditions, approval limitations, and permission requirements. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the meaningful constraint that systems and paths must be exact values taken from list_sources. It does not restate the per-operation parameter mapping, which the schema already covers.

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

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

Opens with a specific verb+resource ('Correct how uploaded files are grouped into systems') and immediately enumerates the four concrete operations (move, split, merge, rename). An agent can distinguish this from siblings like build_map or submit_sources without opening the schema.

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

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

States the precondition to use exact systems and paths from list_sources, and instructs asking the human for the precise choice. This gives clear context for invocation, though it does not explicitly name non-preferred alternatives to route away from.

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?

Beyond the annotations, the description discloses the approval gate and that drafts are inert ('A draft and its licence allow nothing until approval'), a 90-day hold on the workspace and kind after rejection/deletion, value-validation rejection ('turned away'), and auth requirements ('a key that acts and sees the whole map'). These are substantive consequences not implied by readOnlyHint/destructiveHint/idempotentHint, so this exceeds the bar annotations set.

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 'part steps / part time / part whole' labels impose useful structure and the sentences are information-dense rather than padded. However, the prose is telegraphic and the opening sentence bundles scope, venue, approval state and a restriction together, forcing a re-read; some of that belongs after the mode breakdown.

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 18-parameter, three-mode mutation tool with no output schema, the description covers the approval lifecycle, the prerequisites, the per-mode data sourcing, and the fallback tool. The remaining gap is what the call returns (a draft identifier?), which an agent needs in order to follow up, and 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?

Schema description coverage is 100%, so the baseline is 3; the description still adds real meaning, notably that manual_minutes must be a person's explicit statement and never an estimate, that playbook_id can come from get_task_context or from a search result's playbook: token, and that time_statement_id is the latest status token. It does not resolve every parameter pair for the 'whole' part, which keeps it from 5.

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 the concrete verb/resource and splits it into three named sub-operations ('part time', 'part steps', 'part whole'), each with its own object (person-stated minutes, a written playbook's steps, a brand-new playbook). It also frames the outcome ('draft a playbook for a workspace admin to approve ... nothing is in use until then'), so an agent knows this is a proposal-creation tool, not a publish tool. It stops short of 5 because the opening sentence is so compressed that the core purpose is hard to extract on a first read.

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

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

It gives explicit when-to-use rules per mode ('status first and never estimate', get_task_context names the playbook_id where steps are not written yet) and explicit exclusions ('refused for a kind that is covered or has a draft waiting, and then plan the signal with take_signal (plan: true, due in 7 days)'). It also names the skip condition for the time question when the key is not linked to a person, which is exactly the kind of routing guidance an agent needs before calling.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds behavior beyond them: it enumerates the accepted id namespaces, flags that statement:<id> is run-scoped and must be re-searched after a rescan while finding:<finding_key> is stable, and describes the return shape (id, title, text, url, metadata with direct-tool data flattened to text).

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 essential rule — read by id, prefer direct tools if available — is front-loaded, and the id namespace list is compact. The 'second half of the search/fetch pair that connector clients such as ChatGPT require' clause is explanatory padding that a purely operational read could drop.

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 single-parameter read tool with no output schema, the description covers the id provenance, all accepted id formats, stability caveats, and return fields. An agent has everything needed to call it correctly or to decide not to.

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

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

Schema coverage is 100% and the schema already notes the reference format and run-scoping, so the description is partly redundant here. It still adds value by spelling out all six id prefixes (object:, finding:, process:, metric:, statement:, playbook:) rather than the two the schema names, which is what an agent actually needs to construct a valid 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?

States a specific verb and resource ('Read one map document by the id') and immediately scopes it to ids produced by a prior search. Clearly separable from siblings like get_object or list_findings, which the description names 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?

Explicitly states the condition for use ('for a result search handed you, or a finding_key') and the condition against use ('If your client can call the direct tools, use them instead'), then routes to four specific alternatives (get_object, get_process, get_metric, list_findings) with the criteria that select each.

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, openWorldHint=false, and destructiveHint=false, and the description adds useful behavioral context beyond them. It notes key-scope limitations, that truncated counts may be lower bounds, that relationship checks come from the scan, and that wake-up endpoints/deliveries appear only where wake-ups are on. There is 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 front-loaded with 'Orient yourself' and covers many relevant areas, but it is a dense, run-on block with internal jargon and semicolon-separated clauses. It is information-rich but harder to parse than necessary.

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 no parameters, the description carries most of the explanatory burden, and it does list the major overview sections and follow-up paths. Some terms such as 'stated', 'journey', and 'raisers' remain slightly opaque, but the external docs link provides a fallback.

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

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

The tool takes zero parameters, so the schema imposes no parameter-semantics burden. The description does not need to explain parameter usage, and the baseline for zero-parameter tools is appropriately high.

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

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

The description clearly states that the tool provides an orientation overview of the map: domains, objects, row counts, freshness, quality, key scope, relationships, journey, setup, maintenance, and confidence. It distinguishes itself from siblings by naming specific follow-up tools, though the opening 'Orient yourself' is broader than a precise verb+resource phrase.

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 explicitly positions the tool as the orientation step and routes the agent to alternatives: 'route' for a join path, 'get_object' for fields and caveats, and 'ask' for cross-map questions. It also says to use 'journey' to guide the human and mentions 'check_setup' for details, giving clear when-to-use guidance.

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

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

Beyond the readOnly annotations, the description discloses list-mode details such as caveat_count, broken_reason semantics, proposed_for_removal marks, inclusion of older review definitions, and truncation signals. Read mode similarly explains what is returned, including formula representation, object.field grounding, caveats, and recorded values when tracking is enabled.

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 front-loaded with the primary purpose and every sentence carries substantive behavioral information. The definition is dense and somewhat lengthy, but there is little wasted text and the structure moves logically from list mode to read mode to usage guidance and truncation.

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 supplies the necessary return-shape context for both modes, including caveat, broken-state, truncation, formula, grounding, and recorded-value details. No critical information needed to call the tool correctly appears to be 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 already documents name as 'the metric to read, as the list spells it' and that omitting it lists every metric. The description reinforces the dual list/read behavior but does not add syntax or format detail beyond what the schema provides, 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 opens with a precise verb and resource: 'Read one metric in full, or list every metric defined for this workspace.' It distinguishes both operating modes and explicitly routes the agent away from the sibling tool fetch, so the tool's role is unmistakable.

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

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

It states exactly when each mode applies: omit name to list metrics, supply name to read one. It also gives cross-tool guidance by naming configure_metric for starting tracking and fetch as the alternative when the client cannot call this tool, plus the caveat to read caveats before citing numbers.

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 declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context beyond that: the rule-tree structure with layers and rests_on, statement_key expansion, truncation recovery via statements_only, and a real safety constraint to never echo pii=true values. This is genuine added value, not restatement.

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

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

Purpose is front-loaded and no sentence is pure filler, but the long field-name enumeration ('aliases, row_count, row_count_details, grain, field_id, also_called...') is a dense wall that is hard to parse and would read better as structured bullets. Detail is warranted by tool complexity but organization suffers.

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?

Complex tool with 7 params and no output schema, yet the description enumerates what the detail carries (rules, relations with join keys, coverage, PII flags, findings, automations) and points to a full-semantics doc. An agent has enough to call it correctly and interpret the return.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: statement_key 'fetches a compact rule in full', statements_query 'ranks rules; never filter them', and statements_only re-call behavior on truncated answers. These semantics go beyond the schema descriptions, warranting a 4.

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

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

States a specific verb and resource ('Read one object') and immediately scopes what the detail contains: decision statements, fields, relations, caveats. It explicitly distinguishes itself from siblings ('not fetch', 'route for the path', 'ask when the question spans several'), so an agent can select it without opening other 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?

Explicit when-to-use and when-not-to-use guidance naming three alternatives (fetch, route, ask). The opening 'before you act on it' plus the routing rules leave nothing to inference about which tool to pick.

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, non-destructive and closed-world, and the description adds real value on top: truncation behavior ('truncated is true and truncated_note says so') and the origin of the data (deterministic derivation from an object-centric event log built from dated export rows). It stops short of describing ordering or payload shape for the list case, so it is strong but not exhaustive.

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

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

Front-loaded with the core action and the mode branch before any detail. The single long semicolon-chained sentence packs a lot in and the derivation sentence is secondary but still earns its place by explaining what 'discovered' means.

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 return-value burden and does so: case count, happy-path share, step count, median hours between steps, and deviating variants with missing/extra steps. Truncation is covered, so an agent knows exactly what it will get back.

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

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

Schema coverage is 100% and the schema already explains omitting object_type, but the description goes further by spelling out what each mode returns, which is the meaningful consequence of the parameter. It reinforces rather than merely repeats 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?

Opens with a specific verb and resource ('Read one process in full, or list every process') and makes the dual-mode nature explicit. An agent immediately knows this returns process structures rather than raw objects or metrics, distinguishing it from get_object, get_map_overview and get_metric.

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?

States the exact selection rule ('Without object_type it lists them...; with object_type it reads that one') and explicitly routes away from a named sibling: 'Use this, not fetch, when your client can call it.' That is both a when-to-use and a when-to-use-something-else statement.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the bar is low, yet the description adds substantial behavioral detail: the tool is metadata-only and does not fetch real rows, signals carry trust caveats (weak joins, fields not to quote back), statements_only returns {} when nothing applies, and the cursor exists because the client may cut a long answer. That is real context an agent cannot get from 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 front-loaded with the key instruction and roughly the right length, but the middle is a long semicolon-separated dump that mixes mode contents, caveats and warnings into one undifferentiated block. Splitting the three modes into distinct sentences would cost nothing and greatly improve scanability.

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 tool with nested objects, three mutually exclusive modes and no output schema, the description covers the critical ground: mode selection, the metadata-only boundary, the safety framing around suggested_action, truncation/pagination behavior, and a doc pointer for depth. The main gap is that it never sketches the shape of the returned context, which the absent output schema would otherwise require.

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 3 is the baseline, but the description goes further by explaining what each mode yields (task → objects/routes/playbooks/owners; signal_id → evidence/remedy/handling/trust/answer_with/approved_fix) and adds ranking-vs-filtering semantics for statements_query plus the 'keep the same query' constraint on statements_cursor. Only rule_node, statement_key and context are left largely to 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 opening sentence gives a specific verb and scope ('one call equips you for a task, signal or support case') and then enumerates exactly what each of the three input modes returns. It is clearly a context-priming tool distinct from list_signals or get_object, though the dense semicolon chains and internal jargon (layer, rests_on, coverage, weak joins) make the purpose slightly harder to absorb than it needs to be.

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 states plainly when to call it ('Start any work here'), routes the agent elsewhere where appropriate ('fields via get_object', 'open a rule's source only if unclear'), and sets ordering rules ('read payload.checks before acting on one'). It also draws a hard boundary against misuse ('Still metadata: fetch rows in your human's own systems'; 'never a permission'), which is exactly the guidance an agent needs before acting.

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: it defines 'acted on', warns that nulls appear for keys limited to part of the map, and explicitly states Maplith does not estimate value or attribute change to an action, which prevents an agent from over-reading the numbers.

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

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

The purpose is stated up front, but the body is one sprawling semicolon-delimited sentence enumerating every count. Because there is no output schema, that enumeration does earn its place as return-value documentation, but a bulleted or segmented structure would make it far easier to scan.

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

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

With no output schema, the description carries the burden of describing what comes back, and it does so exhaustively across signals, notices, findings, actions, gates, stated value, dead connections, and metrics. Combined with the null-case and no-attribution caveats, an agent has enough to call and interpret this correctly; only explicit sibling routing is missing.

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

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

Schema coverage is 100% and the schema already documents ISO 8601 format, defaults, and the 400-day cap for since/until. The description's 'Default period: the last thirty days (since, until)' restates schema content rather than adding format or constraint detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource: summarise what the workspace got out of its signals over a period, as counts within the key's scope. It is clearly an aggregate-report tool rather than a list/get tool like get_metric or list_signals, though it never explicitly names those siblings to differentiate itself.

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

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

Gives a period default ('the last thirty days (since, until)') and explains scope caveats (gate approvals are workspace-wide, null for a partial-scope key), which implies when it is appropriate. But it never says when to use this instead of get_metric, list_findings, or get_map_overview, and offers no explicit exclusions.

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

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

Annotations only declare destructiveHint=false and readOnlyHint=false; the description adds the far more important behaviors: a person decides on the Business map so no system changes, evidence-first evaluation that returns contradicted with evidence instead of opening a review, the exists/on_map outcomes, and a report-validation policy that refuses the whole report on fractions, negatives, impossible counts, or notes over 300 characters. This is context an agent could not obtain from annotations or 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?

Almost every clause carries information, and the purpose and the confirm-flow are reasonably front-loaded. But it is delivered as one dense, run-on block mixing flag behavior, report behavior, privacy rules and outcome names, making it hard for an agent to parse on a single pass — structure, not length, is the problem.

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 10-parameter tool with nested objects and no output schema, the description covers the outcome vocabulary (contradicted, opened with review_id, exists, on_map), the report-then-read sequence, and the hard privacy rule against sending values, rows, names or ids from the data. Minor gap: the exact shape of the opened/signal payload is only gestured at via 'review_id from the signal's task 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: cardinality must be read from → to, key must be passed exactly as route/get_object returned it, note max length differs between 300 (measurement) and 500 (flag), and counts must be internally consistent or the report is rejected. It also explains per-reason field requirements beyond the enum 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 opening states concrete verbs and objects — question a join, add a missed join, or report counts on a review — so the agent can tell this is a join-review mutation tool, not a read tool like get_object or route. It is specific but the sentence is grammatically tangled ('a join_review signal whose task context says what to count'), and it never explicitly names a sibling it is not.

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 branches: use flag to open a review (with reason-specific requirements: cardinality for wrong_direction, note for works_like_this, key or note for missed), use report to record counts on an existing review. It also states the when-not path — if Maplith's evidence contradicts the claim, nothing opens and you must only retry with confirm:true after the human has seen the evidence — and points to route/get_object as the source of the key.

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 cover read-only, non-destructive, closed-world, so the description spends its space on behavior beyond them: results are sorted by attention urgency, the attention reasons are enumerated (never_run, last_run_failed, status_unknown, object_not_on_map, paused), and it discloses a scope rule not visible anywhere in the schema — only automations whose every bound object is in the key's scope are returned. It also warns the data is registration-derived rather than live.

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 use cases, then return shape, then filters — a sensible order with no filler sentences. It is dense, and the parenthetical attention-reason list is long, but every element is load-bearing rather than redundant.

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

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

There is no output schema, so the description carries the return-shape burden and does: entries carry 'attention', the reasons it needs a look, sorted most urgent first, plus the scope restriction on what is listed. An agent knows what comes back, how it is ordered, and why items might be 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 coverage is 100%, so the schema already documents both filters and the status enum; the description's 'Filter with object or status' adds little. It does add value by introducing the 'attention' concept, whose reason labels (last_run_failed, object_not_on_map) differ from the status enum values (active, paused, never_run, unknown), hinting that status and attention are distinct signals — though it never explicitly reconciles the two lists.

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

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

States a specific verb and resource ('List the automations') and immediately defines what an automation is in this domain ('a flow, a zap, a scheduled job, an agent on a timer') bound to map objects. It also separates itself from the write counterpart by naming register_automation as the tool that adds or updates 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?

Gives two concrete use cases ('see what breaks if an object changes' and 'find dead automation') plus an explicit exclusion: 'it does not run or watch them,' which rules out a plausible but wrong expectation. It also names the sibling that performs writes (register_automation), so the read/write split 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?

Beyond the readOnly and non-destructive annotations, the description explains list completeness via truncated, the meaning of empty_scan values after a scan finds nothing, and the stability of finding_key versus per-run ids. These are exactly the behavioral traits an agent needs to interpret results correctly.

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

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

The description is front-loaded with purpose and sibling routing, then covers key stability, truncation, empty_scan, and status mutation. It is dense but mostly earns its length; the decision/approved sentence slightly overlaps with the status enum documentation.

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 carries the burden of explaining return semantics, and it does: completeness/truncation, empty_scan cases, finding key stability, and the lifecycle meaning of status and decision. An agent has enough context to call the tool and interpret its output.

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 status enum and its meanings are already fully documented in the schema. The description only adds that the filter is optional, which is already implied by the schema; it does not add syntax or format details beyond that.

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: list documented data problems of the workspace, defined as cross-system discrepancies with evidence, recommendation, and lifecycle status. It also distinguishes this catalogue tool from list_signals and fetch, so an agent can select it without opening sibling 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?

It explicitly names alternatives and the conditions that select them: list_signals for new work and changes since a timestamp, fetch for one known finding key, and update_finding_status for changing status. This is clear when-to-use and when-to-use-something-else 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 readOnlyHint/non-destructive/closed-world, and the description adds real context beyond that: scope limited to this key's requests, newest-first ordering, and an itemized list of returned fields (request_id, operation, target, params, reason, timestamp, signal state). With no output schema, that return-shape disclosure is the valuable contribution here.

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 core scope and default behavior are front-loaded, but the passage then rambles into unrelated tooling (waiting_on_maplith, recently_done, unblocked signal) using long run-on sentences. Those sentences do not describe this tool's behavior and actively cost the reader clarity rather than earning their place.

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

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

With no output schema, the description does the necessary work of enumerating returned fields and ordering, which is genuinely complete for the read itself. But it omits pagination behavior given a limit-only schema, and the trailing material about Maplith waitlists describes data this tool does not return, so it neither completes nor cleanly bounds the picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description does elaborate what the status values mean ('pending (a person has not decided yet), allowed, denied or withdrawn'), adding semantic depth beyond the enum, but says nothing about limit or its 1-50 range, leaving the schema to do that work.

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

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

Opens with a specific verb and resource: 'Read your own request_action requests, newest first, and where each stands,' which distinguishes it from request_action (which creates) and from mutation siblings. However, the closing sentences pivot into describing 'waiting_on_maplith' and 'recently_done', which are not what this tool returns, muddying what the tool actually is.

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?

'By default only the pending ones; status all lists every one' gives clear default-vs-override guidance. It also points at request_action with op withdraw as the way to take one back, which is a useful sibling reference. But there is no explicit statement of when to call this versus list_signals or waiting_on_maplith, and the blend of those other tools' semantics into the text leaves the agent unsure whether they are covered 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 only declare readOnlyHint/openWorldHint/destructiveHint, yet the description discloses lease expiry and reopening preserving created_at, cursor pagination, per-group rule judging semantics, the quiet baseline on first evaluation, and rule_cleared on live checks. That is substantial context an agent could not infer from structured fields.

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

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

Purpose and the primary use case are front-loaded in the first two sentences, and most of the remaining content is load-bearing. The rules-judging passage is a dense run-on and could be split for scannability, which keeps it short of a 5.

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 8 optional params, no output schema, and minimal annotations, the description carries the burden well: it covers pagination, ordering, state semantics, polling strategy, follow-up tooling, and points to maplith://docs/signals-and-rules for depth. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining that lease expiry and reopening keep created_at — which directly changes how 'since' should be used — and by tying cursor to the same order. It does not add much for limit or kinds 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 — the scoped queue of signals (typed events) with severity, state, objects and aggregate payloads — and immediately distinguishes it from list_findings for documented discrepancies. An agent can tell it apart from siblings like list_findings and take_signal without opening a schema.

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

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

Explicitly names alternatives and the conditions selecting them: list_findings for documented discrepancies, get_task_context to follow up, take_signal before working, record_action to report. It also gives a non-obvious polling recipe (states [open] without since) for available work.

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 say readOnly/non-destructive/closed-world; the description adds substantive context beyond that: metadata-only with no row values, personal data masking in paths, permission scoping ("a key limited to part of the map sees a file only when every object built from it is in its scope"), and the meaning of unknown in asked data. This is exactly the non-obvious behavior an agent needs.

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

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

Purpose is front-loaded, then the response shape, then the semantic caveats. Dense and largely earning its place, though the later clauses (asked/unknown, work_done_here, re-homing) run together in long semicolon chains and could be split for faster scanning.

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?

No output schema exists, and the description compensates by enumerating the returned fields per system and per file (export/connection, last scan, map provenance, path, format, record count, objects built from it) plus the asked/work_done_here attributes. Nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by clarifying the default (omit = every system) and that naming one system returns that system's files in full, which the schema only implies.

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

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

Opens with a specific verb+resource ("List the systems and files this workspace's scans read") and immediately frames it as the inventory behind the map, which separates it from query-oriented siblings like search, fetch and get_value_summary. An agent can tell what this returns without opening the schema.

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

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

Gives an explicit use case ("Read it before you query a source system, to know which export holds what") and a scoping instruction ("pass system for one system's files in full"). It also points to correct_source_system for the remediation case. It stops short of naming a clear when-not/alternative tool, so not 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?

Goes well beyond the annotations: masking of summaries is "best effort," not_an_issue/wont_fix waits on a person under an approval key, a mismatched signal_version records nothing, and a request whose signal is gone records against the request alone. The only gap is that the readOnlyHint=false / idempotentHint=false pair is never translated into a plain statement about retry/duplicate 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?

One dense paragraph of semicolon-chained clauses that repeats material already fully documented in the schema (resolution, episode, signal_version). The opening scope statement is well front-loaded, but the mode instructions, approval-key rules, and version-stamp warnings are run together with no visual separation, making it hard to parse at call time.

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 12-parameter mutation with nested objects and no output schema, the description covers the failure modes an agent must anticipate: version mismatch, closed-then-reopened episodes, requests pointing at unreadable signals, and hold settlement authority. What it lacks is a plain statement of what a successful call returns or how a rejected call reports itself beyond "you are told."

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter rules the schema cannot express: which parameters belong to the work mode versus the signal mode, that resolution is only meaningful on a signal, and that outcome semantics differ by mode. It also constrains summary length and forbids personal values in work objects.

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

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

Opens with a concrete verb and resource plus the key negative scope: "Record finished work; it changes nothing in your human's systems and starts no scan." It also frames the record as "news in agent activity, not a signal," which separates it from the signal tools. The three input modes (signal/request/work) are named, though the density makes the core purpose slower to grasp than it should be.

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 between modes: "Choose signal_id, request_id for your own allowed request, or work for work with no signal/request," and names an alternative tool with its condition ("Use update_finding_status to change a finding's status instead"). It also states prerequisites ("Needs: a key that may act with approval or autonomously") and the delegate/admin exception path.

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 flag destructive/non-idempotent, and the description adds real context beyond them: atomic server-side validation, single-use consumption semantics, cross-workspace authorization boundaries (any key of the same workspace, never another's), and the full enumeration of refusal states with their consequences. No contradiction with destructiveHint=true or idempotentHint=false.

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 critical rule — one redemption, act only on 'redeemed' — is front-loaded and repeated as a safeguard, which is appropriate for a destructive tool. It is a dense run-on paragraph with a long trailing error-code list, so structure could be tighter, but nearly every sentence carries operational weight.

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, and the description compensates by enumerating the return states (redeemed, already_redeemed, expired, wrong_action, params_mismatch, params_required, params_unbound, revoked, refused) and what each implies. Combined with the auth prerequisite ('a key with an action policy'), an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining *why* each value must come from a particular source (request_id from the job, not the grant; digest as a bearer factor) and by summarizing the HMAC-SHA256 param_digest recipe. Much of this is mirrored in the parameter descriptions, keeping it short of a 5.

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 ('Spend the single-use grant request_action gave you') and immediately distinguishes it from the sibling that issues grants. The one-action/one-redemption scope is spelled out, so an agent knows exactly what this tool does differently from request_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?

Gives explicit timing ('immediately before you perform the allowed action'), the gating rule ('act only if the answer is redeemed'), and the failure-handling branch ('any answer but redeemed means do not act') with per-code guidance. It also names the alternative (request_action) and when to re-ask with a new idempotency_key on expiry.

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?

Goes well beyond the annotations: documents the refusal path for unknown object names with the returned not-found names, the upsert-by-name/system identity rule, the guard that human-confirmed entries keep name/team/objects, that it only writes a map entry and never runs the automation, that the call is logged, and that an autonomous key is required.

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 purpose, then requirements, then optional enrichment, then mutation semantics. Dense but each clause carries distinct information; a couple of the long semicolon-chained sentences could be split.

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

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

For a 9-parameter mutation tool with no output schema, the description covers required inputs, error behavior, idempotency/update semantics, preservation rules, side effects, and auth needs. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3; the description adds a real constraint not visible in the schema — reads/writes need 'at least one' and must match map spelling — and enumerates status values and the optional fields (last run, ending, owner team, step count).

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 ('tell Maplith about / register an automation') and resource, plus the reason the map cares ('so the map knows what depends on each object'). Explicitly separates itself from list_automations, which is described as the read path.

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

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

Covers when to call (reporting an automation, including re-reporting status), what the alternative is ('list_automations shows what is registered'), and the upsert condition ('same name in the same system again updates that entry'). Also specifies the partial-update rule: omit reads/writes to preserve them.

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?

Beyond the annotations, it explains that Maplith never performs the action and never sees credentials, that answers can be allowed, pending, or denied, and what each answer means operationally. It also discloses idempotency_key reuse behavior, approval via approve_url or Slack, and that denials may include a propose_policy path.

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 core instruction is front-loaded, but the description is a long, dense block with many semicolon-separated clauses and embedded policy details. Much of the content is relevant, yet the structure makes it harder to scan and it repeats some schema-level proposal details.

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 multi-operation tool with ten nested parameters and no output schema, the description covers the important answer states, approval flow, withdrawal constraints, denial behavior, and references to external documentation. An agent has enough context to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics: op defaults to ask, withdraw requires a request_id and one-sentence reason, and idempotency_key reuse can return the first answer or be denied. It also explains proposal kinds and the reason format, though some proposal detail overlaps 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 states a specific verb and resource: asking Maplith for permission before acting, withdrawing a waiting request, or proposing a rule change. It explicitly distinguishes this from redeem_action_grant, list_requests, and record_action, so an agent can identify the tool's role without opening the schema.

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

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

It gives explicit when-to-use guidance: ask before acting, do not act while pending or denied, withdraw only while a request still waits and no longer needs a person, and use proposal for rule changes. It also names alternatives such as redeem_action_grant, list_requests, and record_action.

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 establish read-only/non-destructive safety; the description adds substantial behavioral context the annotations cannot: exact per-hop return payload (join_spec with real column names, null when untested), coverage semantics for each metric, basis provenance (declared/measured/guessed), guessed_only fallback rules, and withholding/warning behavior for contradictory or pinned shapes.

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

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

Purpose is front-loaded and nearly every clause carries operational meaning (coverage definitions, basis rules, escalation). The main weakness is structure: the 'Per hop:' sentence is a long run-on packing six distinct return fields, which would be clearer as a list.

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?

No output schema exists, so the description carries the full burden of explaining the return shape, and it does so field by field (join_spec, verb, cardinality, strength, coverage, system, work_done_in, PII). It also covers edge cases an agent would otherwise guess at: null coverage, untested hops, guessed-only hops, shape conflicts.

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

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

Schema coverage is 100%, so the schema already documents from/to. The description adds a small amount of naming semantics ('the answer uses the map's spelling', 'name both objects in any case'), but nothing about format, casing rules, or validation beyond that. 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?

Opens with a specific verb+resource ('Find the shortest verified route between two objects, hop by hop') and immediately distinguishes itself from data-fetching siblings by stating the map 'never returns the data itself.' An agent can tell this apart from fetch, search, get_object, and join_review without opening any schema.

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

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

Explicitly prescribes when to use it ('Use it before fetching data in your human's own systems') and names the escalation path when a hop is wrong or missing ('goes to join_review (op flag)'). It also gives the calling precondition ('Name both objects in any case').

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?

Beyond the readOnly/destructive annotations, it discloses the 50-document shared budget, that per-kind counts are true, and that a 'truncated' flag signals more matches — all non-obvious result behaviors. It also states the matching behavior (case-insensitive) and the scope boundary that relations are excluded.

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, then routing alternatives, then result-id formats for chaining to fetch — dense but each clause carries information. The trailing 'Matching and scope: maplith://docs/mcp' pointer is terse to the point of being opaque, but it is a single clause and does not distract from the core guidance.

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

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

With no output schema, the description compensates by describing result shape (per-kind id formats usable with fetch), the truncation signal, and the result-count budget. Nothing an agent needs to call the tool and interpret its output correctly is missing.

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

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

Schema coverage is 100%, so the detailed substring-matching semantics already live in the schema. The description still adds value by reinforcing case-insensitive matching and pointing at the docs URI for matching and scope, though it does not restate the one-term-not-boolean guidance that the schema carries.

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

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

Opens with a specific verb and resource ('Find items on the map by text') and enumerates the kinds searched (objects/fields, findings, processes, metrics, statements, playbooks). It explicitly differentiates itself from the sibling tools an agent would otherwise confuse it with (get_task_context, get_object, route, ask).

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 trigger ('use it when you do not know the name of what you need') and pairs each alternative with the condition that selects it: get_task_context for a task in words, get_object for a nameable object, route for relations, ask for explanations. When-not guidance is stated ('Relations are not searched').

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): discloses quotas (100 files, 5 MB per call, 2 MB per file, 300 files / 80 MB per upload), a 24-hour deletion lifecycle for unbuilt uploads, refused media types, the 20-sheet/50,000-row Excel expansion, PDF text-layer-only extraction with the scanned-PDF failure mode, and the upload-consent key requirement. That is the behavioral detail an agent needs before calling.

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

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

Front-loaded with purpose and the next call, then constraints in rough priority order. It is dense and semicolon-chained rather than cleanly sectioned, but nearly every clause carries operational information (formats, limits, lifecycle, fallbacks) rather than filler.

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

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

For a two-parameter upload tool with no output schema, the description supplies the full operating picture: prerequisites (upload consent key), size and count ceilings, expiry, unsupported types, failure handling, and the required follow-up call. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the leading folder name becomes the system in the map, a shared root folder must be omitted, and the accepted content formats and encoding pairing are spelled out. It stops short of clarifying edge cases like path collisions or how upload_id interacts with a fresh files array.

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

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

Opens with a specific verb and resource ('Upload export files into your human's workspace to build or rebuild their map') and immediately names the follow-up sibling, build_map. An agent can distinguish this from build_map and list_sources without opening a schema.

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

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

Explicit sequencing ('then call build_map'), an incremental-add path ('call again with the returned upload_id'), and two concrete fallbacks: ask the human to export into one shared folder with one subfolder per system, or have them upload via Data sources › Scans when files are too large. When-to-use, when-not, and alternatives are all present.

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 substantial context beyond annotations: submissions are filed externally, the text leaves the workspace, Maplith tries to mask leaked data, and a follow-up URL or reference is returned. It also discloses a per-workspace daily rate limit. These details matter for a write/submission tool with openWorldHint=true.

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 definition is dense but front-loaded, starting with the core purpose and then covering kind, privacy, and rate limits. Every clause carries operational meaning, though the semicolon-heavy style makes some sentences harder to scan than necessary.

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

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

For an 8-parameter submission tool with no output schema, the description covers the essential behavior: what gets filed, what data must not be included, where the text goes, what reference or follow-up URL is returned, and the rate limit. An agent has enough to call it correctly and safely.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds cross-field guidance, especially that bug reports should bundle tool, problem, expected, and got, and it reinforces the capability-only constraint across all inputs. It stops short of adding syntax or format details beyond the schema.

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

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

The description states a specific action: tell Maplith what its own MCP server lacks or gets wrong. It immediately distinguishes this from reporting a data problem by saying such a problem is a finding, not a suggestion. An agent can tell this apart from sibling tools like list_findings or answer_question.

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 explicitly routes the agent by kind: improvement for missing capability, bug for a failed or wrong Maplith tool. It also gives a clear exclusion: problems in the human's data belong in findings, not here. The default kind and the bug-specific required inputs are stated directly.

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

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

Goes well past the annotations by disclosing hold duration and its default, renewal on re-take, expiration behavior when you report nothing, a per-episode planning rate limit, and severity-based planning caps. 'It changes nothing in any system' plus the key/permission requirement ('a key that may act, with approval or autonomously') fill in the auth and side-effect profile the annotations only gesture at.

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

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

Purpose and state transition are front-loaded, and every clause carries operational information. It is dense and semicolon-chained, though, so the refusal list and planning rules are harder to scan than they need to 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?

With no output schema, the description still covers the full lifecycle an agent needs: how to acquire, how long it holds, how it expires, how to release, how to complete, and what blocks acquisition. Nothing required to call it correctly is missing.

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

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

Schema coverage is already 100%, so the schema baseline is 3, but the description adds rationale the schema lacks: signal_version is an optimistic-concurrency guard ('you take the signal you read, never one a scan has rewritten since') and hours is mutually exclusive with plan, with the renewal semantics behind repeat calls. That is meaningful meaning beyond field-level 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?

States a specific verb and resource ('take' a 'signal') and the exact state transition it causes (open -> in_progress, held by your key). It is immediately distinguishable from list_signals (read) and record_action (finish) named in the same text.

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: use it to claim work now, use plan: true to pick it up for later, use record_action to finish, and record outcome needs_human to release. It enumerates the exact refusal conditions (held by another, planned by someone else and not past date, waiting on a person, done) so the agent can pre-check instead of guessing.

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?

Beyond the annotations, it discloses that the change is logged, that the caller needs a key authorized to act, and that approval mode makes the change wait for an admin while autonomous mode applies it immediately. This adds the permission and approval semantics the annotations do not cover, and nothing contradicts idempotentHint/destructiveHint=false.

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 dense sentences with the lifecycle action front-loaded and no filler, though the telegraphic 'Needs: a key that may act' phrasing is slightly compressed and takes a re-read. Overall efficient for the amount of routing and permission context it packs in.

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

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

Covers purpose, sourcing of the id, alternative tool, logging, authorization, and the approval-vs-autonomous outcome. No output schema exists, but the description gives enough about what happens after the call (logged; may wait for approval) that an agent can invoke it correctly.

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

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

Schema description coverage is 100% and the enum values are already explained in the schema, so the description adds little parameter meaning beyond repeating the four statuses. The only extra hint, that finding_id comes from list_findings, is also present in 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 (change) plus resource (finding's lifecycle status) and enumerates the four target states, so scope is unambiguous. It also explicitly separates itself from record_action, which handles work on a signal rather than the finding's 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?

Gives an explicit trigger ("when your human has decided what a finding is"), names the alternative tool and the condition that selects it (record_action for work on a signal), and tells the agent where the finding_id comes from (list_findings). Both when-to-use and the alternative routing are spelled out.

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