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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real behavioral detail on top: the dry-run/token confirmation protocol, that every relation is written on both sides, that matching is scoped by number within a document, and that update_existing gates mutation of matched items. It does not describe partial-failure behavior or rate limits, which keeps it short of a 5.

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 and the dry-run rule before the example. The plan example is dense but every line demonstrates a distinct field or ref form, so it earns its space; the closing sentences efficiently compress matching, bidirectional relations, and non-deletion. Slightly long, but not padded.

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

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

For a complex, nested-input mutation tool with no output schema, the description covers the write semantics, the confirmation gate, matching rules, and deletion behavior. The gaps are project_url and the read-back format, but the dry-run confirmation loop covers the critical path an agent needs to call this safely.

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

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

Schema coverage is 0%, so the description carries the full burden and largely succeeds: it documents the plan's shape (update_existing, entities, relations, unlink), the meaning of key/class/number/document/parent/attributes, and defines what a ref can be. dry_run and confirm_token are explained via the workflow, though project_url is never mentioned and several nested fields are only shown by example rather than explained.

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 pair and resources: 'Create or update entities and relations in one save, then read everything back to verify.' The 'in one save' framing distinguishes it from the sibling innoslate_update, which presumably handles single-item mutations. An agent can tell what this tool does and how it differs from atomic edit tools.

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

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

Gives an explicit mandatory workflow: always call dry_run=true first, show the summary and confirm_token to the user, and only re-call with identical plan, dry_run=false, plus the token after approval. It also states exclusions implicitly via 'Nothing is deleted' and describes matching scope ('matched by number inside their document only'). This is well beyond minimum 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 readOnly=false, destructive=false, idempotent=false, openWorld=true, so the safety profile is largely covered. The description adds real value by disclosing that it REPLACES an existing file and that a dry-run/confirm_token flow applies. It still omits auth/permissions requirements and what the dry-run response looks like, so it sits at a solid 3.

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

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

Two tight sentences, front-loaded with the action and scope, then the replacement warning, then the workflow pointer. No filler, though the parenthetical about Artifacts is slightly interruptive.

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

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

For a 6-parameter mutation tool with no annotations details, no output schema, and 0% schema description coverage, the description is too thin. An agent cannot confidently form a dry_run/confirm_token call sequence or interpret id/path/project_url from this text alone.

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

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

Schema coverage is 0% across 6 parameters, so the description must carry the load. It only clarifies property_name (defaults to 'File' on Artifacts), leaving id, path, dry_run, project_url, and confirm_token entirely undocumented in both schema and description. One param explained out of six is a clear shortfall.

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 (upload/attach) and resource (local file into an entity's file property), and clarifies the property naming on Artifacts. It also discloses the replacement semantics. It does not explicitly differentiate from siblings like innoslate_update or innoslate_apply, but the purpose is unambiguous.

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

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

The reference to 'same dry-run and confirm_token flow as innoslate_apply' gives a usable procedural pointer and implies a two-step confirmation workflow. However, it never says when to use this tool instead of innoslate_update (which presumably sets other properties), nor any prerequisites or 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the return-content hint ('with the entity each is on') and the marker-feedback context, which is genuinely useful, but it omits filtering behavior and pagination details.

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

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

A single efficient sentence with no wasted words, front-loading the core action. The parenthetical adds value rather than bloat.

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

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

For a tool with two undocumented parameters and no output schema, the description is too thin. An agent cannot tell what 'unresolved_only' does or what 'project_url' expects, leaving a real gap before invocation.

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

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

Schema description coverage is 0%, and the description says nothing about either parameter. The purpose of 'project_url' (which project context) and 'unresolved_only' (filter to open comments) is left entirely undocumented, so the description fails to compensate for the coverage gap.

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

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

States a clear verb+resource ('Review comments on the project') and adds a useful hint that these are 'often the marker's feedback'. It distinguishes the tool well enough, though it does not name any sibling or explain how it relates to retrieval tools like innoslate_get.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. The parenthetical about the marker's feedback implies context but does not tell the agent when comments are relevant or what prerequisites exist.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the shape of the result: ordered contents with depth, text, labels and trace links, which tells the agent what effort/volume to expect.

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

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

Two compact sentences with the return content front-loaded and the parameter hint second. Nothing is padded, though the second sentence could be fused more tightly.

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

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

For a read-only tool with no output schema, the description conveys the return structure and the key identifier format. It falls short on the full_text, max_depth and project_url parameters and any limits, so it is adequate but not fully self-sufficient.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It does document the required 'document' parameter thoroughly (id, number like 'UN.1', or exact name), and 'depth'/'text' loosely map to max_depth and full_text, but project_url is entirely undocumented in both places.

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 what the tool returns, a complete in-order document tree with depth, text, labels and trace links, which is a specific and recognizable resource. It does not explicitly contrast itself against siblings like innoslate_get or innoslate_read_workspace, but the 'everything inside a document' framing is clear enough for an agent to distinguish it.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives. The agent is left to infer that this is the right tool for retrieving a whole document rather than a single node or workspace.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context the annotations don't: results come back as 'short rows' rather than full entities. It does not cover pagination behavior or result ordering.

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

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

Front-loaded with the purpose, then a compact filter list with inline clarifications, then a return/alternative note. Dense with no filler, though the filter enumeration runs slightly long.

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 notes that results are short rows and points to innoslate_get for full entities, which is enough for an agent to act. Pagination parameters (limit/offset) are implied but never explained, leaving a minor gap.

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

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

Schema coverage is 0%, so the description carries the full burden, and it delivers: text (words in name or description), number (exact), number_prefix with an example ('SR.1.'), and document (id, number or name, only items inside it) all get real semantic detail. However limit, offset, and project_url are left completely unexplained, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource ('Search entities') and immediately names the sibling it is not ('use innoslate_get for one entity in full'). An agent can distinguish innoslate_find from innoslate_get 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?

The description routes the agent to innoslate_get when a single full entity is needed, and 'Combine any filters' clarifies how the filter set is meant to be used. It gives clear usage context but no explicit exclusions or edge cases for when search should not be used.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds real behavior beyond them: a numeric ref can match several entities because numbers repeat, and every match is returned along with the documents it sits in. That multi-match/ambiguity disclosure is genuinely useful for an agent.

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

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

Two dense sentences with no filler; the payload description is front-loaded and the ref caveat follows. Slightly compressed phrasing ('the target's number and name') costs a little clarity but nothing 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?

With no output schema, the description compensates by summarizing the return shape (entity plus all relations and containing documents). The single gap is the undocumented project_url parameter, which is minor for a 2-parameter 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 0%, so the description carries the burden. It fully explains 'ref' (id or number, and the multi-match consequence), which is the important parameter, but 'project_url' is left entirely undocumented in both schema and description.

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

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

States a specific resource and its full payload: 'One entity in full: text, labels, attributes, and every relation with the target's number and name.' An agent can distinguish it from retrieval-by-search siblings like innoslate_find. It does not explicitly name those siblings, so it stops short of a 5.

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

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

Usage is implied by the ref semantics (id vs number, multiple matches), but there is no explicit when-to-use statement or comparison against alternatives such as innoslate_find or innoslate_read_workspace. The agent must infer that this is the single-entity fetch tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds what the call surfaces (workflow, login state, file destinations) without contradicting those hints, though it omits any note on output format or freshness of the login state.

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

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

Three short sentences, zero waste, and the imperative "Start here." is front-loaded so the agent reads the routing cue first. Nothing to trim.

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 no-parameter tool with no output schema, the description carries the burden of describing what comes back, and it does name the three returned payloads. It is complete enough to call correctly, though it could say more about how the returned workflow should be used next.

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 no parameter semantics to explain; per the rubric a zero-parameter tool earns the baseline of 4. The description correctly implies there is nothing to configure.

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 clear purpose for a zero-parameter bootstrap tool: it returns the step-by-step workflow, the current login state, and where files go. It does not explicitly differentiate itself from siblings like innoslate_status or innoslate_initialize, which likely overlap on login/workflow information, so it falls short of a 5.

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

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

"Start here." is an explicit, unambiguous usage cue telling the agent to call this first before other tools. However, it names no alternative or condition for skipping it, and does not clarify its relationship to innoslate_status or innoslate_initialize, 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?

The description explicitly states the tool 'writes PROJECT_MAP.md, NOMENCLATURE.md and snapshot.json into the project workspace', i.e. it produces persistent side effects, while the annotations declare readOnlyHint=true (no modification). This is a direct write-vs-readOnly conflict of the same kind the framework asks to flag, so per the rule it scores 1 even though the rest of the behavioral disclosure (reads entities/schema/comments/members, processes guides, returns a summary) is detailed.

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 instruction ('Survey the whole project before any write') is front-loaded, and the rest is dense but justified detail. It is slightly long with a compound final sentence, 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 complex setup tool with no output schema, it covers what gets read, what gets written, how guides are handled, what it returns, and where to read the full results. The main gaps are the unexplained project_url and the unresolved readOnlyHint conflict, which complete only after the annotation is reconciled.

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

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

Schema description coverage is 0%, so the description must carry the burden. It does a good job on guides_dir (folder or single file, PDF/DOCX, text saved under guides/, numbering patterns compared), but project_url is never explained, leaving one of two parameters undocumented in both schema and prose.

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+resource ('Survey the whole project') and immediately scopes it ('before any write'), which cleanly distinguishes it from siblings like innoslate_schema, innoslate_find, or innoslate_get that read narrower slices. An agent can tell this is the whole-project survey/provisioning step 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 timing ('Run once per project, and again after big changes') and sequencing ('before any write'), and routes the agent forward to innoslate_read_workspace for the full outputs. It stops short of naming which sibling it replaces/excludes (e.g., vs innoslate_get_started or innoslate_status), so it is clear context rather than a full when/alternatives matrix.

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

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

Annotations already declare this a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds real behavioral value beyond that by defining the errors-vs-warnings outcome model and what the caller should do with each, which is not encoded in any structured field.

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 and the pre-apply condition are front-loaded in the first and last lines. Parameter details are packed inline somewhat telegraphically (nested curly-brace notation), but every sentence contributes and there is no filler.

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

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

With no output schema, the description should fully define the return shape; it gestures at errors vs warnings but does not describe the result structure an agent will parse. For a lint tool with four parameters and no required fields, the coverage of inputs is good but output expectations remain thin.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it documents the items object shape (number, name, text, rationale?), the document selector (id/number/name), and extra_banned with a concrete regex example. Only project_url goes undocumented, which is a minor, self-evident gap.

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

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

States a specific verb and resource: 'Check requirement wording' as a pre-write lint step, and notes it can also target an existing document. It differentiates by timing relative to writing and names the downstream sibling innoslate_apply, though it does not distinguish itself from the similarly-named innoslate_quality_check.

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 clear usage context ('before writing it' and 'before innoslate_apply') and an actionable rule (errors must be fixed, warnings need a human). It offers no explicit comparison or exclusion versus the overlapping innoslate_quality_check sibling, 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?

Goes well beyond annotations by disclosing the blocking wait behavior, the 300s default, the env/.env credential auto-fill, and the security rule that passwords are never tool arguments. It does not say what happens if the wait times out or login fails, which is the main remaining behavioral gap. The readOnlyHint/idempotent annotations are not contradicted by opening a browser session.

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 one-sentence purpose followed by compact per-parameter notes and a credential-handling sentence. No filler, and the most important constraint (passwords never accepted) is stated last for emphasis.

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 only 2 parameters, no output schema, and no nested data, the description covers purpose, both params, and credential behavior adequately. Missing only failure/timeout semantics, which is minor for a browser-wait 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 description coverage is 0%, so the description must compensate, and it does: project_url is explained as the address-bar URL with an example format, and wait_seconds as the login wait duration with its default. It stops short of stating allowable ranges or the unit boundary beyond the default, keeping it just under 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+resource+mechanism: open the project in a browser window and wait for login. No sibling tool does anything comparable; the interactive-browser framing alone distinguishes it from all the data-oriented innoslate_* siblings.

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

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

The description implies the prerequisite nature of the call (login must precede work) but never says so explicitly, nor names an alternative or a when-not condition. It does clarify credential handling, which is contextual guidance rather than usage routing.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-destructive mutation. The description adds valuable context beyond that: 'Innoslate stores the scores on the requirements; nothing else changes', which precisely discloses the write side effect and its scope. It does not mention permissions or re-run cost, so not a 5.

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

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

Two tight sentences: purpose and return shape first, side-effect disclosure second. Every clause earns its place, including the UI mapping that helps an agent confirm identity, and there is no filler.

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

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

With no output schema, the description usefully covers the return content (per-requirement Quality Score, failed checks, sorted lowest first) and the mutation side effect. However, the opaque `document` parameter and the entirely undocumented `project_url`/`timeout_seconds` leave the agent guessing on invocation details.

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

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

Schema description coverage is 0% for 3 parameters, so the description carries the full burden and largely fails. It hints that the target is a 'requirements document' (mapping loosely to `document`) but says nothing about whether that is a name, ID, or path, and never mentions `project_url` or `timeout_seconds`.

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 (Run Quality Check) and resource (requirements document), and even maps to the Innoslate UI location (More > Quality Check). It is clear what the tool does, though it never explicitly contrasts itself with the sibling innoslate_lint_requirements, which an agent might plausibly confuse it with.

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

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

The implied usage (score a requirements document against Innoslate's built-in checks) is inferable, but there is no explicit when-to-use, when-not-to-use, or named alternative such as innoslate_lint_requirements. Given a near-identical-sounding sibling exists, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior in disclosing pagination ('Long files come in pages: pass next_offset back as offset'). It stops short of explaining the offset/max_chars interplay or what truncated reads look like.

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

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

Two sentences, front-loaded with the core action, then paging behavior. No filler, no redundancy with the schema.

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

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

For a read tool with no output schema, the description covers the key behaviors an agent needs: valid identifiers and paging. The unmentioned max_chars and project_url are the only remaining gaps, and the paging note carries most of the operational weight.

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 0%, so the description must carry the full load. It explains 'name' richly and implies 'offset' via the next_offset paging hint, but 'max_chars' and 'project_url' are never mentioned, leaving half the parameters undocumented.

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 ('Read a file from the project workspace') and enumerates the canonical names ('map', 'nomenclature', 'audit') plus relative-path support. It implicitly separates itself from read_local_file by scoping to the 'project workspace', though it never names that sibling 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?

It gives concrete values for the 'name' argument and thus implies what the tool is for, but it never states when to choose it over read_local_file or list_local_files, nor any prerequisites. Usage is inferable rather than spelled out.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds two pieces of non-obvious context: output defaults to the workspace's reports/ folder unless out_dir is given, and an invalid report name yields a list of valid reports rather than an opaque failure.

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

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

Three tight sentences, front-loaded with the core action and examples, then the naming caveat, then the output location. Nothing is padded, though the example list slightly crowds the opening.

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

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

For a 4-parameter tool with no output schema and full annotation coverage, the description supplies the missing pieces an agent needs: valid report name format, error recovery, and output destination. Only project_url and the 'document' identifier remain unexplained.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It clarifies report_name via examples and notes out_dir overrides the default reports/ location, but 'document' is only implied, 'project_url' is never addressed, and the default report name in the schema is not reinforced.

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 (download) and resource (Innoslate document reports) and anchors it with two concrete examples ('Basic Document Output (DOCX)', 'RTM Output (XLSX)') plus the UI path where the names come from. An agent can distinguish this from read/get/apply siblings without opening any schema.

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

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

Usage is implied through the UI navigation hint and the fallback 'if the name is wrong, the reply lists the reports this document offers', which tells the agent how to recover from a bad report_name. There is no explicit when-to-use/when-not statement or named alternative among the many siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that relations include their inverses and that class_name confines results, but says nothing about result size, caching, or auth, so it adds only modest context.

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

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

Three short lines, front-loaded with what is returned before the parameter hints. Every line earns its place, though the kind list and class_name note read as loose fragments rather than a cohesive sentence.

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

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

No output schema exists and schema coverage is 0%, so the description carries full weight. It names the entity categories returned but gives no shape or nesting detail, and omits project_url entirely, leaving the agent with an only partially complete picture for a 3-parameter introspection 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?

With 0% schema description coverage, the description must carry the parameter burden. It documents the 'kind' enum values well and explains class_name's scope, but leaves project_url completely undocumented, so two of three parameters are covered at best.

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 enumerates the exact resource contents it returns: classes, relations (with inverses), labels, and properties. That is specific enough to distinguish it from data-fetching siblings like innoslate_get or innoslate_find, though it lacks an explicit verb (list/return) and never names a sibling.

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

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

It implies when to use the tool by documenting the 'kind' selector and the class_name restriction, which tells the agent this is a schema-introspection call. However, it never states when to prefer this over alternatives such as innoslate_get_started or innoslate_document_tree, nor any prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds genuine behavioral context by listing the three checks it performs, which tells the agent what state information comes back, but it says nothing about return format or how to act on a negative result.

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

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

A single compact sentence with three clauses, zero filler, and the essential content front-loaded. Slightly informal question phrasing rather than declarative statements keeps it from a 5, but it wastes nothing.

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 parameterless, read-only status probe with annotations covering the safety profile and no output schema, the description covers what the agent needs to decide to call it. It is complete enough; only the follow-up routing is 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?

The tool takes zero parameters and schema description coverage is 100%, so there are no parameter semantics to explain. Baseline of 4 applies; no parameter information is missing.

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 enumerates three concrete things the tool reports (browser running state, current project, login validity), so an agent can tell it is a status/diagnostic probe. It is not phrased as a verb+resource and does not name a sibling, keeping it short of a 5, but the purpose is unambiguous.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named (e.g. innoslate_login when the login is invalid, or innoslate_initialize when the browser is not running). The diagnostic intent can be inferred from the questions, but nothing routes the agent to the right follow-up tool.

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

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

Annotations declare the write/idempotency profile, so the bar is lower, and the description adds the meaningful dry-run plus confirm_token two-phase flow. It also clarifies that labels 'replaces' while add_labels appends, a real behavioral distinction. It stops short of stating auth requirements or what happens to unspecified fields.

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

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

Two tight sentences, front-loaded with the core action and then the field/flow detail. No filler or redundancy.

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

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

For a nested-fields mutation tool with no output schema, the description covers the crucial fields-object semantics and the confirm flow adequately. Minor gaps remain around permissions and error/validation behavior, but the essentials for correct invocation are present.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does enumerate the fields-object keys (name, number, description, description_html, labels, add_labels, attributes, relations, parent, document) with the important replaces-vs-append note. It leaves wrapper params like project_url and id semantics undocumented, so compensation is partial.

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?

'Change one existing entity by id' gives a specific verb and resource and scopes it to a single entity. It contrasts implicitly with the bulk-oriented innoslate_apply, though it doesn't fully spell out when to prefer one over the other.

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

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

The reference to 'Same dry-run and confirm_token flow as innoslate_apply' implies a two-step preview/confirm workflow, which is genuine usage context. However, there is no explicit when-to-use guidance, no exclusions, and no statement of which siblings (e.g. innoslate_apply, innoslate_get) this should be chosen over.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely new value by stating the output includes size and readability (a permission check), but says nothing about the default-recursive behavior, which materially changes what gets listed.

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

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

A single tight sentence with the operation front-loaded and no filler. It earns its brevity, though it omits the recursive detail that would justify a few extra words.

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

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

No output schema and 0% parameter coverage, yet the description only partially describes returns and omits the default-recursive scope entirely. For a tool where recursion defaults on, an agent cannot predict whether subfolders are included.

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

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

Schema description coverage is 0%, so the description must compensate — and it does not. The 'recursive' parameter (default true) is never mentioned despite significantly changing the result set, and 'folder' is only implied by 'a local folder' with no format guidance.

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

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

Clear verb+resource: 'List the files in a local folder', and it names what the listing contains (size, readability). It implicitly contrasts with the sibling read_local_file via the list-vs-read verb, but never names an alternative explicitly, so it stops 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?

There is no when-to-use, when-not-to-use, or alternative routing. 'a local folder the user pointed at' hints at conversational context but gives the agent no criteria for choosing this tool over read_local_file or the innoslate_* family.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: paged/chunked output for long files and the fact that audio/video are not directly readable. It stops short of describing error behavior or the shape of the paged return.

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

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

Three sentences with no filler, and the format list is front-loaded so the agent learns scope immediately. The pagination and audio/video notes follow in a logical order. Slightly dense format enumeration is the only cost.

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

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

For a read-only tool with no output schema, the description covers formats, chunking behavior, and an important input boundary. The gaps (max_chars semantics, what happens on unreadable/oversized files) are minor given the annotations already convey the safe-read profile.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does for offset by explaining the pagination round-trip, but it references a 'next_offset' field that is not an actual parameter, and max_chars (page size) and path are never explained. Meaning is added for one of three parameters only.

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 specific resource ('Plain text of a local document') and enumerates supported formats (PDF, DOCX, XLSX, PPTX, CSV, JSON, Markdown, TXT, VTT/SRT), which pins down exactly what 'read' returns. It does not explicitly contrast with the sibling list_local_files, but the read-vs-list distinction is inferable from the names.

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 two usable constraints: pagination ('Long files come in pages: pass next_offset back as offset') and a boundary ('Audio and video need a transcript first'). However, it never states when to prefer this tool over list_local_files or what to do for unsupported inputs, so guidance is implied rather than explicit.

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