IceShore

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

Annotations already flag destructive and idempotent, but the description adds substantial non-redundant behavior: UPSERT semantics, one-note-per-node limit, the exact error reasons (ref_path_not_found with matched_prefix/candidates, adl_unavailable), the fact that "$ref" targets are not followed, and the contexts/useCases naming trap. This is far beyond what the annotations 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?

Front-loads the core action and auth requirement, then layers constraints, error semantics, and output shape in a dense, orderly block. It is long, but nearly every sentence carries distinct information; only mild redundancy with the schema descriptions costs it the top score.

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

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

For a mutation tool with no output schema, the description supplies the required params, the auth/permission model, the overwrite semantics, the failure modes, and even the response shape ({ ok, mode, defined_at, updated_at }). An agent has everything needed to call it correctly and interpret the result.

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 parameters are already documented, and the description's parameter notes (200-char normative text, ref_path server validation, lang) largely restate the schema. The ref_path matching/candidates detail is useful but already mirrored in the schema description, 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+resource: saving a normative humanNote onto an ADL node, and explicitly notes the UPSERT overwrite behavior with a max of one effective note per node. It is clearly distinguishable from the read/delete siblings (get_notes, delete_note) without opening any schema.

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

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

Gives the precondition (login required, editor or admin role) and points to iceshore://guide/common for the draft-then-save workflow. It does not explicitly name when to prefer this over siblings like delete_note/get_notes, so it stops short of full when/when-not 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 cover readOnly/non-destructive/closed-world, but the description goes further: it discloses the success shape (userId + organizations with workspace_id/name/role), the failure shape (error string on invalid/expired token), and the role restriction on registration. It does not mention refresh/rate-limit behavior, but adds real behavioral value beyond the annotations.

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

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

Front-loaded and organized with explicit 入力/出力 structure, so the reader knows exactly what is returned. Slightly verbose in the final two sentences about workspace_id reuse, but every line carries actionable information.

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

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

No output schema exists, so the description must carry the return contract — and it does, covering both success and failure payloads plus role constraints. Nothing an agent needs in order to call this and interpret the result 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?

The tool takes zero parameters, so per the baseline there is nothing to document. The description's 'Input: none' correctly confirms this.

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

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

States a specific verb+resource: it returns the connection and authentication status to IceShore. There is no sibling tool with overlapping purpose (add_note, create_content, list_projects, etc. are all content operations), so an agent can unambiguously identify this as the auth/connection probe.

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 never explicitly says when to call this tool (e.g. 'call before other tools to verify the token'), but it does give downstream usage context: the returned workspace_id feeds create_content / commit_uploaded_codes and list_projects filtering, and it warns that only admin/editor roles can register. That is implied rather than explicit 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?

Adds substantial behavior beyond annotations: max 100 per batch, 10-minute URL expiry, parallel uploads allowed, duplicate code_id in one batch causes an error, and staging isolation per user×project. This is consistent with idempotentHint=false (fresh URLs each call). Return shape is also sketched, though minor details like auth failure or quota behavior are absent.

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

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

Front-loads the core purpose and is organized into input/output sections, so an agent can locate details quickly. The embedded curl example and several tangential notes (staging split, ADL root handling) make it denser than strictly necessary, though most lines earn 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?

No output schema exists, but the description enumerates the return fields (project_id, urls with code_id/upload_url/content_key, expires_in=600), which compensates. Combined with constraints, error conditions, and the commit_uploaded_codes handoff, an agent has everything needed to call and chain 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, but the description adds semantics the schema lacks: files are 1–100 and required, urls[] order mirrors input files[] order, project_id is for appending to an existing project, and duplicate code_id fails. That is meaningful additional meaning over the schema.

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

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

States a specific verb and resource: issues presigned PUT URLs for multiple provisioning files in a single call, with an explicit cap of 100. The batch scope is unambiguous, and the contrast with a single-file alternative is legible from the name plus '複数...1 回の呼び出しで' even though the sibling is not named.

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 clear operational context: login required, upload via HTTP PUT, then feed results into commit_uploaded_codes, with a note that an ADL root file can be added as one more entry. It stops short of explicitly routing the agent away from the singular request_upload_url sibling or stating 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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, but the description adds far more: merge semantics (matching code_id overwrites, new code_ids append, unspecified files are preserved), that quality evaluation/diagrams/version/status are generated server-side, that version increments per save, that login is required, and the 400 error when a code_id was not PUT. This is exactly the kind of context annotations cannot carry.

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 purpose well and uses labeled sections (merge rules, input, output), but it is dense and long, with several facts (is_root max 1, workspace_id behavior) duplicated verbatim from the schema, which dilutes rather than concentrates the signal.

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

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

With no output schema, the description still states the return shape (id plus diagram URL) and covers auth requirements, server-side side effects, merge/preserve rules, and error conditions. An agent has everything needed to invoke this mutation correctly, including the prerequisite confirmation of the target workspace.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including adl_root, overview, workspace_id and the is_root flag. The description restates the input list and the two ADL-root-passing modes, but adds little that the schema descriptions do not already contain, 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?

States a specific verb and resource: it commits files previously PUT to the request_upload_url/batch_request_upload_url staging URLs into an IceShore project's codes, creating new projects or merging into existing ones. It explicitly names the sibling tools it is not (save_content's full replacement, delete_code for deletion), so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use context (after a curl PUT to staging), when-not-to-use (file deletion is not handled — use delete_code or save_content), and the key alternative distinction (MERGE appends/updates vs save_content's full replacement). The workspace_id requirement even spells out that the agent must confirm the target workspace with the user 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 only declare the mutation/safety profile; the description adds auth requirements (login; org admin/editor or 403), irreversibility (workspace fixed at creation, cannot change via MCP), size limits (~5MB per call, 6MB sync ceiling), and a pre-save secret-masking behavior (***MASKED***). These are meaningful behavioral traits not derivable 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?

Front-loaded with purpose, alternative routing, then format details; every section earns its place for a complex multi-part payload. However it is long and the codes example partly duplicates the schema, so it is not maximally tight.

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 documents the return (new id prefixed 'd' and diagram URL; ok:false + error on failure), the required overview contents, the document guides for ADL/IaC import/changelog, and the fallback path for oversized uploads. An agent has everything needed 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 real meaning beyond the schema: the consequence of missing adlRoot (screen renders empty), the distinction between lang (category) and fmt (file format), and the workspace_id default/confirmation rule. It stops short of only restating schema text.

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

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

States a specific verb+resource (新しい IceShore プロジェクトを作る) with scope (ADL と添付ファイルを登録する), and explicitly distinguishes itself from the sibling save_content for updates. An agent can tell this apart from save_content 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 and when-not: new creation vs save_content for updates, plus routing guidance for large uploads (batch_request_upload_url + commit_uploaded_codes over ~5MB) and a mandatory workspace-confirmation workflow before calling. Login and 403-on-missing-org-role conditions are stated.

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

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

Annotations cover destructive/idempotent/readOnly hints, and the description adds real context beyond them: login is required, adlRoot cannot be deleted, the structure diagram is regenerated server-side on save, and removed:false semantics. This is a rich disclosure for a destructive mutation.

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 action, then the constraint, then the alternative, then I/O. Efficient overall, though the explicit input/output recaps partially duplicate structured data (the output recap earns its place since no output schema exists).

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 return shape and the meaning of removed:false, plus auth and constraint info. An agent has everything needed 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 description coverage is 100% with both params documented, including the adlRoot restriction on code_id, so the baseline is 3. The description restates the required inputs but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource (delete one file from project codes) and immediately scopes it against the sibling save_content. An agent can distinguish this from save_content/add_note 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?

Explicitly says when to use it (single-file read/write, faster than resending all codes) and names the alternative (save_content full replacement) for the case it cannot handle (adlRoot). Covers the when-not case too.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it clarifies the delete is LOGICAL (row retained), discloses the auth/permission requirements, and explains the restore-by-add_note side effect. That is exactly the kind of context annotations cannot carry.

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, then prerequisites, side effect, and structured 入力/出力 blocks. Every sentence earns its place with no redundancy.

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

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

Despite having no output schema, the description supplies the return shape ({ ok, mode: "deleted"|"not_found" }), plus auth and side-effect context. 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 description coverage is 100% – both content_id and ref_path are documented in the schema, including the ID format constraint. The description only restates that both are required, adding no syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: logical deletion of an ADL node's humanNote, with the exact mechanism (is_deleted=1). It also names the sibling add_note and describes the restore relationship, so an agent can distinguish it from get_notes/add_note without opening schemas.

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

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

Explicitly states prerequisites: login required, editor or admin permission. It also implies the when-to-use case via the add_note restoration note. It lacks an explicit 'do not use when…' exclusion, 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 already cover the safety profile (readOnly/non-destructive), and the description adds substantial behavioral context beyond them: anonymous access returns only official samples and otherwise yields 401, per-mode latency ('meta' saves 10+ seconds, 'detail' may take ~30 seconds), and the return envelope shape. This is exactly the auth and performance disclosure the 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?

Front-loaded with the authentication caveat, then purpose, id source, mode tradeoffs, and output shape in clearly labeled sections. It is somewhat long and the mode section repeats schema text, but every block is navigable and earns its place.

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

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

For a read-only retrieval tool with no output schema, the description covers everything needed to call it correctly: auth behavior, required id format ('d'-prefix vs the unusable 'I...' URL slug), default and alternative modes with cost implications, and the return envelope. Nothing material 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 schema already documents id, mode, and locale. The description's mode explanations largely duplicate the enum descriptions in the schema, so it adds little beyond the baseline; a 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Returns the ADL and attachments for one IceShore project') and names the sibling tools that supply the required id (list_projects / list_samples). An agent can distinguish this lookup tool from list_projects, list_samples, and save_content without opening any schema.

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

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

Gives concrete usage contexts (referencing existing projects, verifying the result of a save/update, with get_content(mode='detail') positioned as the canonical post-save state). It routes the agent to list_projects/list_samples for the id, but stops short of explicitly stating when NOT to use it.

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

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

Beyond the readOnly/non-destructive annotations, the description discloses that no authentication is required (anonymous use) and that an unknown name returns a list of available names — both behavioral traits the annotations do not convey. It also states the output format (markdown/JSON, English body).

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 most important constraint (no auth needed) and then proceeds through purpose, alternative, names, input, and output in labeled lines. It is dense and earns most of its length, though the bracketed auth notice and multi-line layout make it slightly heavier 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, the description correctly supplies the return format and language. Combined with the auth disclosure and the unknown-name fallback, an agent has everything needed to call this single-parameter tool correctly.

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

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

Schema coverage is 100% so the schema already documents the name parameter and its short-name/URI-path forms; per the rubric the baseline is 3. The description adds value by glossing each of the main guide names ('analysis' = business impact/dependency analysis, etc.) and by noting that an unrecognized name yields a listing, which the schema does not.

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

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

States a specific verb and resource ('returns IceShore guide documents by name') and enumerates the guide topics (ADL writing, registration, analysis). It is clearly distinguishable from siblings like get_content or get_notes, which fetch user data rather than static documentation.

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

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

Explicitly tells the agent when to use this tool ('for clients that don't support MCP resources') and names the alternative ('supporting clients can read the same content via resources/read'). It also gives the condition for an unknown name, which routes the caller to the fallback listing behavior.

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 and destructiveHint=false, so safety is covered; the description adds real behavioral context beyond that: login is required, at most one valid note per node, and orphaned notes (ref_path no longer present in the ADL) can appear after deletion or renaming. It does not discuss pagination or rate limits, but the added constraints are substantive.

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

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

Front-loaded with the core action, then organized into labeled sections for purpose, the refs parameter, an edge-case caveat, and the output shape. Dense but each section carries information; no obvious filler, though it is on the longer side for a two-parameter read tool.

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

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

With no output schema present, the description supplies the return shape ({ code, id, data: { notes: [...] } } with field names), the auth requirement, the item cap, and the orphan-note caveat. Nothing an agent needs to call or interpret the result 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 both id and refs are already documented, which sets the baseline at 3. The description goes further by explaining the refs omission semantics (all up to 500) and the meaning of orphaned ref_paths, adding interpretive value beyond the schema's own wording.

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: returns the project's humanNote (normative human-authored notes on ADL nodes), with the login requirement and the one-note-per-ref_path constraint front-loaded. An agent can distinguish it from the sibling mutation tools add_note and delete_note purely from the description.

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 enumerates when to reach for it: checking before editing an existing project, referencing nodes that show human editing traces (_meta.d starting with "h:"), and answering questions about a specific node. It stops short of naming when not to use it or routing to a specific alternative sibling, so it is clear context but not full when/when-not 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact sha256 derivation (SHA-256 of the data string, matching local `shasum -a 256`), which tells the agent how to interpret results and how to compare against local files. It does not describe pagination or return format limits, so a 3 is appropriate.

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 purpose, then adds the sha256 semantics, the usage workflow, and the input/output shape in clearly separated lines. Every line carries distinct information; nothing is redundant 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?

With no output schema present, the description supplies the return structure ('codes: [{code_id, isRoot, lang, fmt, size, sha256}]'), which is essential for the agent. Combined with the hashing semantics and the upload workflow, the agent has everything needed to call and use the result 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 single project_id parameter is already documented in the schema (including the 'd'-prefixed internal ID note). The description only restates 'input: project_id', adding no semantics beyond the schema. Baseline 3 is correct when the schema does the 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?

States a specific verb and resource ('returns metadata list of the codes array of an existing project') and explicitly scopes out what it does NOT return ('file content data is not included'). This distinguishes it cleanly from get_content, which fetches file content, without the agent needing to open either schema.

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

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

Gives an explicit when-to-use case (differential upload decision) and names the downstream alternative path: files whose sha256 mismatches or is absent should be sent via request_upload_url / batch_request_upload_url → commit_uploaded_codes. Both the condition and the alternative tools are stated, not inferred.

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 and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: login requirement, plain-text output with total/totalPages, and page-size default/max. It stops short of describing rate limits or failure modes.

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 usefully sectioned (用途/ページング/サンプル/入力/出力). Some content (paging defaults, range/sample relationship) duplicates the schema, which slightly inflates the length.

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 specifying the return format (id+title plain text, trailing total/totalPages). Inputs, paging, filtering, and sibling relationships are all covered, leaving nothing an agent needs 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 description coverage is 100%, and the schema itself already documents range values, workspace_id source (auth_check), and paging defaults. The description restates paging and the omitted-range default, adding only marginal meaning beyond the schema, 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?

Uses a specific verb+resource ("ユーザが閲覧権限を持つプロジェクト/ADL構成図の一覧を返す") and disambiguates from siblings by stating that official samples come from list_samples, not here. An agent can distinguish this from get_content and list_samples 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?

Explicitly states when to use it ("作業対象のプロジェクトの特定", as the starting point before get_content) and names the alternative for samples (list_samples). The range semantics also document what is included/excluded by default.

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/destructiveHint=false, but the description adds valuable context beyond them: no authentication required, usable anonymously, and the result set is pinned to official samples even when logged in. It does not cover rate limits or error behavior, but the added auth/scope semantics are meaningful.

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?

Labeled sections (用途 / list_projects との違い / ページング / 入力 / 出力) are front-loaded and each line carries distinct information. Slightly repetitive since paging defaults appear in both the paging and input lines, but overall efficient.

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

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

For a simple read-only list tool with no output schema, the description covers auth requirements, scope, alternative routing, paging, inputs, and the return shape (ids + titles with total/totalPages). 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 description coverage is 100% and both parameters are fully documented there (defaults, max 100). The description restates the paging defaults (page=0, itemperpage=24) but adds no syntax or meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('returns a list of public structure diagrams of official sample workspaces') and explicitly names the sibling it is not (list_projects). An agent can distinguish it from list_projects 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?

Explicitly states when to use it ('reference examples for new designs, building on samples') and draws the exact boundary against list_projects ('list_projects = projects you have permission to view, not including samples; this tool = official samples only'). Nothing 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?

Annotations only declare it is a non-read-only, non-idempotent, non-destructive call. The description adds real behavioral facts: 10-minute URL expiry, HTTP PUT semantics, 403 when targeting another user's project_id, per-user×project_id staging, and last-write-wins when the same code_id is re-issued.

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 multi-file alternative are front-loaded, and the curl invocation example is directly actionable. It is dense and long, but nearly every sentence carries distinct operational information, so little is wasted.

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

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

Covers the full lifecycle – auth requirement, URL issuance, upload mechanics, expiry, project_id handling, and the commit path – and even enumerates the return fields despite no output schema. 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 is 3, but the description adds meaning beyond the schema: omitting project_id makes the server allocate a new one, later calls in a session should reuse the returned project_id, and re-issuing the same code_id overwrites at commit time. The required/optional inputs and outputs are also restated usefully.

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: issuing a presigned PUT URL to S3 for one provisioning file, with the login prerequisite noted. It explicitly distinguishes itself from the sibling batch_request_upload_url for multi-file cases, so an agent can route 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?

Names alternatives and their selecting conditions: batch_request_upload_url for N files, create_content/save_content for clients that cannot run a shell, and commit_uploaded_codes as the downstream step. It also notes is_root:true in commit_uploaded_codes for the ADL root 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?

Annotations declare destructiveHint=true; the description explains the destruction concretely — unspecified existing files are deleted under full-replace, deletion requires allow_code_deletion, and unchanged files must be resent. It also discloses non-annotation behavior: server-side version increment, auto status logic, and secret masking returning a list of redacted locations.

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

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

Front-loads the core action, auth, and sibling routing in the first sentence, then the destructive full-replace rule. Dense but every clause carries operational weight; a briefer invocation-side summary at top would help skimming.

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

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

For a destructive, auth-gated mutation with no output schema, this covers auth, replacement semantics, required shape of codes/notes, server-controlled fields, masking behavior, and points to a guide for edge cases. Nothing material is omitted.

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

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

Schema coverage is 100% so baseline is 3, but the description adds cross-field meaning: codes shape matches create_content with one adlRoot entry, notes must be an array of {at,content}, and info.version/status in overview are server-controlled and ignored if sent. Slightly over-generous is avoided; these are genuine semantic additions beyond the schema strings.

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 (updates ADL and attachments of an existing IceShore project) and explicitly distinguishes itself from create_content for new creation and from commit_uploaded_codes for partial merges. An agent can route correctly without opening schemas.

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

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

Explicitly says when not to use it (create_content handles new), names the merge alternative (commit_uploaded_codes), and states the auth requirement plus required role (owner / admin / editor). Full-replace semantics vs partial merge is spelled out.

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