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

Goes well beyond the annotations: it discloses the file-based mechanism (XojoRunProject.txt / XojoCompileErrors.txt), the exact error line format, that compile errors fail the call, that a success leaves the app running in the debugger, the 10-second request handoff, and the cleanup of the request file on failure. None of this is inferable from readOnlyHint=false / destructiveHint=false alone.

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 mode constraint and the run_project contrast, then layers mechanism, error format, and failure mode in a logical order. The temp-filename detail and the sentence on stop_project overlap slightly with what an agent needs, but no sentence 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 carries the return-value burden and does: error line format, the failure case where errors are reported, and the success case where the app launches. Timeout behavior, prerequisites, and the stop path are all covered, which is complete for a two-parameter run 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 both parameters, their defaults and the max are already documented in the schema. The description adds only indirect color: the file-based mechanism explains why project_dir might be needed, and the 10-second handoff window hints at the wait semantics. It does not clarify the relationship between that 10-second handoff and wait_seconds, so the baseline 3 holds.

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 ('runs the project and returns its compile errors') and pins the scope to Agentic Mode only (Xojo 2026r3+). It explicitly contrasts with the sibling run_project, so an agent can pick it apart from the near-identical alternative 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?

Gives explicit when-to-use (Agentic Mode on, or when the IDE socket is unavailable), when it fails (mode off / project not open, with a 10-second criterion), and names the follow-up tool ('stop it with stop_project'). It also pre-authorizes repeated calls as the user's opt-in, which removes a common agent hesitation.

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 the annotations: exact return format ("No errors or warnings found." or one line per issue with type, message, location), the failure contract (any error fails the call, warnings alone do not), the up-to-one-minute wait, and the IDE/project prerequisite. These are things annotations cannot express and an agent needs before invoking.

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

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

Front-loaded with purpose, then scope, then return format, then failure semantics, then preconditions – a sensible ordering. It is dense with facts rather than padding, though the parenthetical and semicolon clauses make it read like a checklist rather than tight prose.

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

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

There is no output schema, so the description correctly takes on the burden of describing the return value and error behavior. Combined with the timeout and environment prerequisite, an agent has everything needed to call this 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 coverage is 100%, so the enum-like values, the default, and the select_project_item prerequisite are already documented in the schema description. The description only adds the performance rationale ("faster") for item scope, which is marginal added value, so the baseline 3 applies.

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

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

States a specific verb and resource ("Analyzes the current Xojo project for compile errors and warnings without building") plus the exact categories of findings (unused variables, type mismatches, deprecated API). The "without building" qualifier and the static-analysis framing clearly separate it from build_project and run_project in the sibling list.

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 guidance on the scope choice: pass scope="item" for a faster analysis of the current selection, default "project" for everything, and it names the prerequisite tool (select_project_item). It also states the environmental precondition (Xojo IDE running with the project open). It stops short of naming when to prefer this over build_project or lint_project_file, so not a 5.

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

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

Discloses traits annotations cannot express: a 30-minute wait with the operation continuing past it, server-wide blocking of other requests until the IDE responds, the prerequisite of a running IDE with the project open, and the critical caveat that a success has been reported with no app written so the artifact must be verified on disk. Annotations only say non-read-only, idempotent, non-destructive; the description adds far more.

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

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

Purpose first, then usage gate, then return behavior, then the failure caveat, then operational constraints — each sentence carries a distinct fact an agent needs. Dense but no filler or repetition of the title.

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 long-running mutation with no output schema, it covers everything an agent must know to invoke and interpret it: return values in both success and failure cases, invisible runtime errors, truncation/blocking semantics, and environmental prerequisites. Nothing material is left implicit.

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 parameters (reveal, build_type) fully documented including the enum-like build target codes, so the schema does the heavy lifting. The description adds no parameter-level syntax or format detail beyond it. 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?

Opens with a specific verb and resource ('Builds the open Xojo project into a standalone app') and immediately contrasts with the sibling run_project, which is the tool most likely to be confused with it. An agent can distinguish build vs. run without reading 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 gate ('Call it only when the user asks for a build') plus a preferred alternative and its rationale ('offer run_project first: a run catches errors a build misses'). This is exactly the when/when-not/alternative structure that prevents misuse.

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 the annotations: a set is read back so a non-matching name is reported rather than silently ignored, a get of an unknown name returns empty (indistinguishable from a genuinely empty constant), and a set persists only until save_project. These are non-obvious failure and persistence semantics an agent would otherwise have to discover by experiment. Consistent with destructiveHint=true and idempotentHint=true, since the operation overwrites an existing value in place.

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?

Five tight sentences, front-loaded with the get/set purpose, then the existence requirement, then failure semantics, then the rename escape hatch, then persistence and prerequisites. No sentence is redundant and no filler is present.

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

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

For a two-parameter mutation tool with no output schema, the description covers everything an agent needs: prerequisites (IDE running, project open), what is mutated and what is not, what happens on a miss for both modes, when the change becomes durable (save_project), and where to go for rename/retype. 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 baseline is 3, and the description earns above that by explaining the dual get/set mode and what omitting value means operationally, plus the difficulty of resolving bare names against a nonexistent constant. It does not add format or syntax detail beyond what the schema's fully-qualified-name example already provides.

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 pair: gets or sets the value of a project constant in the Xojo IDE, with the constraint that the constant must already exist. It distinguishes itself from the closest sibling (property_value for properties, scaffold_code_block for editing #tag Constant lines) implicitly through the rename guidance, though it never names those siblings directly.

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?

Clear about scope: value changes only, not rename or retype, and it names the alternative route for those (edit the #tag Constant line on disk, which scaffold_code_block writes). It also states the prerequisite of a running IDE with the project open. It lacks an explicit 'use X instead for properties' redirection to the closest sibling, which keeps it from 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?

Beyond annotations, the description discloses that the IDE assigns IDs, new methods/properties are blank and untitled and remain selected, and items stay in the IDE until save_project. It also states the prerequisite that the Xojo IDE must be running with the project open.

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

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

The description is front-loaded with the action and parent behavior, and every sentence carries relevant operational information. It is somewhat dense and run-on, but there is little wasted content.

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

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

No output schema exists, yet the description explains the return value as the new item's location. It also covers lifecycle, selection state, prerequisites, follow-up naming, and deletion limitations, which is complete for this mutation 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 parameter documentation already exists. The description adds useful semantics: parent_location is selected first, omitting it uses the current selection, and the new item's location is returned; it also clarifies that set_declaration should follow without a location.

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: creates a new item in the open Xojo project using the IDE's own command. It distinguishes this from hand-editing the .xojo_project file and from the missing delete capability, so an agent can identify the tool's unique role.

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

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

It explicitly says to use this tool, never a hand edit of the project file, to add items. It also gives the follow-up workflow with set_declaration and explains that there is no matching delete tool, including what to do instead.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false): it discloses the failure mode without a session, the prerequisite IDE/project state, and critically that the call returns as soon as the IDE accepts the command without reporting the new line or variable values. That last point prevents an agent from expecting state back and re-polling, which is exactly the kind of context structured fields cannot 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 purpose, then actions, then prerequisites, then return behavior in a logical order with no filler. The inline action glosses partially duplicate the schema description, costing a little tightness, but each sentence carries information an agent needs.

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

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

No output schema exists, and the description compensates by explicitly describing what the call does and does not return. With a single required parameter fully documented and a clear failure condition, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics by glossing each action ("step_over" executes current line, "step_into" steps into a method call, "step_out" exits the current method, "resume" continues, "pause" halts). This resolves any ambiguity about what the terse enum values mean in practice.

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 ("Controls the Xojo debug session") and immediately enumerates the five concrete actions, so an agent knows exactly which operation family this is. It is clearly distinguishable from siblings like run_project or stop_project, which manipulate the session lifecycle rather than stepping through 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?

Explicitly states the precondition: an active debug session started with run_project, and that the call fails without one. It also states the IDE must be running with the project open. The only gap is that it never names stop_project as the way to end a session, but the when-to-use condition is unambiguous.

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

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

Annotations already flag destructive=true and idempotent=false; the description goes further and explains atomicity ('If old_string is missing or ambiguous nothing is written'), whitespace-failure recovery ('returns the exact text to retry with'), and that the change lives in the IDE until save_project. Those are the exact operational facts an agent needs before invoking a destructive edit.

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?

Dense and front-loaded: purpose, mechanism, matching constraint, sibling preference, failure behavior, persistence, and prerequisite in six tight sentences. No filler and no repetition of the name/title.

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

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

For a destructive mutation with no output schema, the description covers failure modes, persistence, and prerequisites well, and even hints at error return content. It doesn't say what a successful response looks like (e.g., confirmation, diff, or new code), which is the one remaining 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 100%, so baseline is 3, but the description adds behavioral consequence beyond the schema: the exact-match/occurrence rule and what happens (nothing is written) when old_string fails to match or is ambiguous. The location parameter's 'current location if empty' behavior is left entirely to the schema, which keeps it from 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?

Opens with a specific verb+resource and mechanism: 'targeted edit ... by replacing an exact substring, leaving everything else untouched.' It also explicitly distinguishes itself from siblings by naming set_code and stating that it reaches the same items as get_code.

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 routing rule — 'Prefer this over set_code for edits to existing code' — plus a prerequisite: 'Needs the Xojo IDE running with the project open.' Together with the note that changes persist only after save_project, the when/how is fully covered.

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 establish readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the implementation basis (keyword heuristic over request text and planned tool names), the absence of project/IDE access, and that no real token count is produced. That is exactly the caveat an agent needs to avoid over-trusting the rating.

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

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

Three sentences, each earning its place: what it returns, what it actually is (and is not), and when it is worth calling. The most decision-relevant caveat is placed before the usage hint.

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, yet the description fully specifies the return shape (rating plus reasons plus cheaper alternatives). Combined with the stated limitations and the fully documented two-parameter schema, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the schema already documents both parameters, including which tool names affect the rating and which words raise it. The description only reinforces that the heuristic reads request text and planned tool names, adding no format or edge-case 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 and resource — rates a planned request's likely token cost — and names the exact output scale (LOW/MEDIUM/HIGH) plus the extra payload (reasons, cheaper alternatives). No sibling tool does anything comparable, so an agent can select it unambiguously.

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?

"Most useful before documentation-heavy or project-wide work" gives a clear triggering context, and "treat it as a prompt to narrow scope rather than a measurement" tells the agent how to act on the result. It stops short of explicit when-not-to-use guidance or naming an alternative, but there is no obvious alternative among the 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?

Goes well beyond readOnly/idempotent annotations: discloses the Navigator side effect of passing a location, the error case for bad paths or code-less items, the empty-body behavior, the fact the declaration line is excluded, and a version gate for window/control event handlers. Slightly short of 5 only because the exact error/return shape is described qualitatively rather than concretely.

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?

Dense and front-loaded — the core behavior leads, then errors, scope limits, sibling linkage, and prerequisites. A few clauses (the location/omitted restatement) duplicate the schema, which is minor waste but not 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?

No output schema exists, and the description compensates by explaining exactly what the returned text is (body only, no declaration line) and what an empty result means. Combined with the IDE prerequisite and version caveat, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100% and the schema already documents the dot-separated format, the 'Controls' segment and the omit-for-editor behavior. The description restates the omit semantics and adds the Navigator-selection consequence, but provides no meaning beyond what the schema carries, 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 (returns) and resource (the code body of a method/event handler/code item) plus the scope (open Xojo project). It is clearly distinguishable from siblings like get_selected_text, set_code and edit_code without needing to open any schema.

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

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

Explicitly defines the two call modes (with location vs. omitted for the editor's current item) and routes the agent to the sibling that consumes the output: 'Copy edit_code's old_string from this output.' It also names an alternative for older IDE releases (.xojo_window file) and states the runtime prerequisite (IDE running, project open).

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, closed-world behavior, so the description adds context beyond them: the returned value is mutable state changed by select_project_item, other tools implicitly depend on it, and the Xojo IDE must be running with a project open. Missing only failure-mode detail (e.g. what is returned when nothing is selected).

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 return contract, then dependency semantics, then prerequisites. Every clause carries distinct information; 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?

No output schema exists, so the description carries the return-value burden and does so exactly, including a concrete example. It also covers the runtime prerequisite and the cross-tool dependency, which is everything an agent needs to call and interpret this tool.

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

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

Zero parameters, so the baseline is 4; nothing about inputs needs explaining. The description instead spends its budget on the return-value shape, which is more useful than parameter prose would be here.

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

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

States a specific verb and resource and immediately pins down the exact return format ('<path> (<type>)' with a concrete example), so an agent knows precisely what it gets. It explicitly distinguishes itself from get_project_info (same item plus project path/version) and select_project_item (mutates the selection).

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 rule: tools with an optional location parameter act on this item when omitted, so check this value first. It also names the two adjacent alternatives and what each does differently, leaving nothing to inference.

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

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

Goes beyond the annotations by explaining that a missing log file is a normal, self-describing result, that deletion only happens when clear is set (reconciling destructiveHint=true with a default non-destructive read), and that no IDE is required. It omits any mention of return size, truncation, or whether the full file is always returned, which matters since there is no output schema.

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

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

Front-loaded with the resource and its origin, and every sentence carries information (alternative tools, empty-result semantics, clear behavior, no-IDE requirement). Some sentences are densely packed with parentheticals, which slightly hurts scannability.

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

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

For a single-parameter read tool with no output schema, it covers the return artifact, the normal empty case, the destructive-flag consequence, the setup prerequisite (adding the handler per usage-guide.md), and the sibling alternative. Nothing essential to a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds rationale the schema lacks: clear deletes the file so the next crash starts a fresh log. That explains the consequence of the flag rather than restating it.

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

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

Names a specific artifact (/tmp/xmcp_debug.log), its producer (a built Xojo app's App.UnhandledException handler), and its purpose (seeing an exception in a built app). It also explicitly distinguishes itself from get_system_log, which reads System.DebugLog output, 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?

States when to use it (crash in a built app), when not to (a debug run, where the IDE debugger catches exceptions), and the alternative (get_system_log for System.DebugLog). Exclusions and alternatives are explicit rather than implied.

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

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

Beyond annotations, it discloses meaningful behavior: an empty value clears the description, a set returns 'OK' and persists only until save_project, giving a location also changes the IDE selection, and the IDE must be running with the project open. These are exactly the side effects an agent needs.

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

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

The description is front-loaded with the core read/set distinction and then tersely covers side effects and prerequisites. Every sentence adds useful information with no filler.

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

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

With no output schema, the description still explains the return value ('OK' or the description text), covers persistence across save_project, notes the selection side effect, and states the required runtime environment. Nothing essential is missing.

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

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

Schema coverage is 100% and already documents both parameters, but the description adds meaning beyond the schema: it explains that an empty value clears the description and that supplying location also selects that item in the IDE.

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 dual verb (reads or sets) and resource (Description of a project item or member), and explicitly distinguishes it from code-related siblings by clarifying it is the Inspector note, not the item's code.

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 clearly states the read vs. set behavior based on presence of the value parameter, and that omitting location defaults to the selected item. It does not explicitly name alternative tools like get_code or set_declaration, but the conditions for use are otherwise clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the environment prerequisite (IDE running, project open) and the return shape (one fact per line). That is meaningful context an agent needs before calling, though it says nothing about failure behavior when no project is open.

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 what is returned and followed by the call-ordering rule. The field enumeration is dense but each item maps to a real return value; only the version/Agentic Mode detail borders on surplus.

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 must describe the return payload — and it does, item by item. Combined with the stated prerequisite and the sequencing advice relative to lint_project_file, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies a no-argument call by describing output 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?

States a specific verb and resource ("Returns facts about the project open in the Xojo IDE") and enumerates exactly which facts: project path, project directory, Xojo version, selected location and type, Agentic Mode state. That enumeration separates it from siblings like get_current_location and get_code, which return only a subset.

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?

"Call it first when working on files on disk" gives explicit ordering guidance and names the dependent tools (lint_project_file, direct edits) that need absolute paths. It also states the prerequisite that the IDE must be running with the project open. No explicit when-not-to-use case, 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 declare it a safe read (readOnlyHint, idempotent, non-destructive), yet the description adds materially more: the exact first-line output format 'start=<offset> length=<n>' with offset semantics, the failure mode ('fails if no code editor is active'), and the environment precondition. That is precisely the residual 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?

Dense but purposeful, with the return shape front-loaded in the first sentence and the usage/sibling routing following. The opening sentence is long and packs return format, offset definition and failure mode together, which slightly hurts scanability but no sentence 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?

There is no output schema, yet the description fully specifies the return shape and its header line, the failure case, and the operating precondition. For a zero-parameter read tool, nothing an agent needs in order to call it correctly 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?

Zero parameters, so baseline is 4. The description nevertheless supplies the meaning the caller needs: the offset unit is characters from the start of the item's code, which is the same coordinate system set_selected_text expects — useful given the sibling relationship.

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 text selected in the Xojo IDE's code editor. It also names the boundaries against siblings (get_selected_text vs. get_code vs. set_selected_text), so the agent can distinguish this tool from them without opening the schema.

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

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

Gives explicit when-to-use cases ('see what the user has highlighted', 'find offsets for set_selected_text') and a clear when-not-to ('to read a whole item, use get_code'), naming the alternative tool directly. Prerequisite condition (IDE running with project open) is stated 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 readOnly/idempotent/non-destructive/closed-world, and the description still adds real behavioral detail: only framework-logged lines are returned, with a documented fallback of up to 200 raw entries labelled as such, plus the meaning of an empty result and the fact that no IDE is required. That is materially more than the annotations provide.

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 behavior and no filler sentences; each clause carries information. It is a dense single paragraph, and the trailing 'Needs no IDE' is the only bit that feels tacked on rather than essential.

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

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

There is no output schema, and the description compensates by explaining what is returned (framework log lines, or up to 200 labelled raw entries) and what an empty result implies. An agent has everything needed to call it and interpret the response.

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 both `seconds` and `process_name` are already documented with defaults, bounds, and naming rules. The description's mention of 'a debug run started by run_project, or a built app' lightly contextualizes process_name but adds no syntax or format detail 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?

States a specific verb and resource: returns recent System.DebugLog output of a Xojo app from the macOS unified log via `log show`. It is clear what comes back and under what circumstances (debug run via run_project, or a built app), but it never names the very similar sibling get_debug_log, so an agent must infer the boundary itself.

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

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

Gives concrete operating context: use it for a debug run or a built app, prefer it over MessageBox for tracing, and if the result is empty add a System.DebugLog call and query again. It stops short of an explicit when-not-to-use or a named alternative among the 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?

With annotations already declaring readOnly/idempotent/non-destructive/closed-world, the description still adds real value: it defines the error and warning classes, states that findings—errors included—are a normal result rather than a failure, and clarifies that only an unreadable or wrong-type file fails the call. That failure-mode disclosure is exactly the context annotations cannot 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?

Purpose is front-loaded and every sentence carries information, but the warnings sentence is a long run-on ('and things Xojo loads but resolves on its own terms: blocks out of order or after #tag ViewBehavior, and a Flags value...') that could be split or tightened for faster scanning.

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

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

No output schema exists, and the description compensates fully by describing the return format ('No issues found' or a count plus one 'error|warning: line <n>: <message>' per finding) and the failure conditions. Nothing needed to call and interpret 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?

Only one parameter, and schema description coverage is 100%, with the schema already telling the agent to use get_project_info for the project directory. The description adds no syntax or format detail beyond saying the target is a file on disk, so the baseline 3 applies.

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

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

States a specific verb and resource (checks a .xojo_code or .xojo_window file on disk) and scopes it as catching what the IDE reports badly or not at all, which distinguishes it from the sibling analyze_project. An agent can tell what it does and on what artifact without opening the schema.

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

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

Explicitly says when to run it ('after editing a project file directly and before revert_project'), naming a sibling in the workflow sequence. The 'reads the file only and needs no IDE' clause also tells the agent this is an offline check, complementing the live-IDE 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 mark this as read-only, idempotent, non-destructive, and not open-world. The description adds important behavioral context beyond that: unfiltered output is about 1,600 entries and 150 KB, it fails if installed documentation was not found, and it needs no IDE.

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

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

The description is compact and front-loaded: it states what the tool returns, then scale and filter guidance, then sibling-tool routing. Every sentence contributes relevant information without waste.

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

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

There is no output schema, but the description explains the return shape as one title and URL per line. It also covers scale, failure conditions, IDE independence, empty-result semantics, and alternatives, which is complete for a simple one-parameter listing 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?

The schema already documents the single filter parameter at 100% coverage, including its case-insensitive substring behavior. The description adds useful practical meaning by warning that unfiltered output is very large and therefore the caller should pass a filter, plus it clarifies the relationship between API page titles and lookup_class.

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 lists pages in the local Xojo documentation index, one title and URL per line. It also distinguishes itself from sibling tools by explaining that search_docs searches page text and lookup_class reads one page.

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 to use this tool to find which pages exist, names the alternatives search_docs and lookup_class, and gives a clear condition for using the filter. It also notes that no match is a normal result, which prevents misinterpreting an empty list as failure.

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

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

Goes well beyond the annotations (which already cover readOnly/idempotent/non-destructive): it discloses the return shape (tab-separated names), the empty-result and nonexistent-location behavior (a message, not an error), the Xojo 2026r3 limitation on member listing, and the environmental prerequisite. That is the class of information an agent cannot get from structured fields.

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

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

The core scope is front-loaded in the first clause, and each subsequent sentence carries a distinct fact (member limitation, empty-result behavior, prerequisite). It is dense but four sentences of similar weight, so the priority ordering is slightly flatter than ideal.

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 responsibly covers return format (tab-separated names), soft-failure messages, and the required IDE state. Minor residual ambiguity remains about whether the response is a single tab-delimited string or a list of records, and about ordering of the returned items.

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

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

Schema coverage is 100% and the property description already documents the dot-separated path and omitting for top level. The description explains what happens semantically when location is empty versus a folder, but largely restates the schema rather than adding format, edge-case, or naming-example detail beyond it. 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 ("Lists the project items directly under a location in the open Xojo project's Navigator") and immediately defines the two scoping modes (top level when location is empty, folder contents otherwise). It also carves out what it does NOT return (item members), and names the sibling tool get_project_info that supplies the folder paths, so it is distinguishable from neighbors without opening a schema.

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

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

Clear context for use: call it to enumerate Navigator contents, and for member information the description redirects to reading .xojo_code/.xojo_window via get_project_info. It also states the prerequisite (Xojo IDE running with the project open). It stops short of explicitly excluding any sibling that might look like an alternative enumerator, so it is not a full when/when-not map.

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 non-destructive/non-open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: it reads the installed documentation and fails if none was found, needs no running IDE, truncates output at 100,000 characters, and reports errors with suggestions. Those are real behavioral disclosures, but the default output shape is largely restated from the schema's `full` parameter, so this is solid-but-not-distinctive.

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

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

A single dense paragraph, front-loaded with the core behavior and then failure modes and alternatives. Every sentence carries either a routing rule, a default behavior, or an error-handling instruction; nothing is 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?

There is no output schema, and the description compensates by describing exactly what comes back: markup-stripped description and member tables with signatures, or raw reStructuredText when `full` is set, plus size limits. Combined with the named alternatives and prerequisite (installed docs, no IDE), an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by explaining the interaction between defaults and `member`: the default view is trimmed to description plus member tables, and `member` yields one member's full entry. It also characterizes the scale of `full` (class String over 70,000 characters of raw reStructuredText), which helps the agent avoid a costly call. Minor redundancy with the schema's own `full` description keeps it from a 5.

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

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

States a specific verb and resource ('Returns the reference page for one Xojo class, control, data type or other API, by name') and explicitly distinguishes itself from search_docs and list_doc_topics. The name-resolution behavior (case-insensitive, Desktop/Web prefix fallback) is concrete enough that an agent can predict what a given input will retrieve.

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 routing: 'Use this when you know the name; use search_docs for concepts or a name you are unsure of, and list_doc_topics to browse page titles.' It also states what happens on failure paths (unknown class suggests search_docs; unknown member lists documented members), which steers the agent's recovery behavior rather than leaving it to guess.

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?

Substantial context beyond the annotations: values are always strings, a set returns 'OK' without read-back so a follow-up get is needed to confirm, changes live only in the IDE until save_project, and the Xojo IDE must be running with the project open. That is exactly the kind of side-effect, verification, and prerequisite information the annotations don't 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?

Purpose comes first, then scope limits, then behavioral notes, then the prerequisite. Every sentence carries distinct information; the only near-duplication is the string-values note, which is minor and reinforces a frequently botched detail.

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

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

For a two-parameter getter/setter with no output schema, the description covers naming, value format, return behavior, persistence, and environment prerequisites. An agent has everything needed to call this correctly and verify 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 coverage is already 100%, so the baseline is 3. The description still adds value with a third example ('App.SupportsDarkMode') and a negative name example ('Window1.PushButton1.Caption') that clarifies the naming grammar — something the schema's two examples don't establish on their own.

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?

A clear verb+resource pair ("gets or sets a FRAMEWORK property of a project item") followed by three concrete example property paths. The scope limit (framework properties, not user-added ones, not window controls) separates it cleanly from siblings like constant_value or set_code without needing 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 states the situation this tool is for ("the supported way to change app and build settings, which otherwise live in the .xojo_project file that must never be hand-edited") and names two exclusions. What's missing is direct sibling routing — it never says what to use for custom properties or control captions, leaving the agent to guess among the 30 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 flag destructiveHint=true, but the description goes well beyond them by spelling out exactly what is destroyed (every unsaved IDE change, including the user's), that an interactive IDE prompt may appear that a caller must accept, and the precondition that the IDE must be running with the project open. That is the level of behavioral disclosure a destructive no-param tool 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?

The irreversible warning and user-consent requirement are front-loaded, and each subsequent sentence adds a distinct constraint (disk trigger, save_project exclusion, Agentic Mode exception, IDE prerequisite). It is dense with semicolon-joined clauses and could be split for readability, but no sentence is 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 parameters and no output schema, the description supplies everything an agent needs before calling: preconditions, destructive consequences, consent requirement, an interactive prompt it may encounter, and the sibling call it must avoid. Nothing material is left to inference.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema-coverage baseline of 4 applies. The description correctly spends no words on arguments and instead covers preconditions and side effects.

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

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

The description names a specific operation on a specific resource: closing an open Xojo project without saving and reopening it from disk. It also states the purpose of that action (the IDE picks up on-disk edits), which lets an agent distinguish it immediately from save_project or build_project.

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

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

It gives an explicit trigger (after editing .xojo_code or .xojo_window files on disk), an explicit anti-pattern (do not call save_project in between, which would overwrite the edits), and an explicit exclusion (not needed in an Agentic Mode project). It also requires asking the user first, so the routing decision is unambiguous.

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

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

Annotations already declare destructive=true and openWorld=true, but the description goes well beyond them: it enumerates concrete destructive capabilities (quitting Xojo, closing/reopening projects, creating or deleting items, writing files, DoShellCommand), documents the output protocol (first Print wins, errors outrank output, silent scripts report success), warns that Return prevents the completion signal and leads to waiting until timeout, and notes runtime errors arrive with no message or line number. It also states the IDE must be running.

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

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

Purpose is front-loaded in the first clause, followed by output contract, then hazards, then routing guidance — a sensible escalation order. Every sentence carries either a behavioral fact or a decision rule; there is no filler despite 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 supplies the full return-value contract, error behavior, timeout risk, destructive capability list, and the prerequisite that the IDE be running. For a destructive, open-world escape hatch with only two parameters, nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real semantics on top: the return-value convention for the 'script' parameter (Print, first non-empty Print wins, error precedence, silent = success) and the consequence of an early Return. It does not restate the timeout parameter's blocking behavior, which the schema already covers in detail.

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 ('Executes an arbitrary Xojo IDE script') and immediately frames its position in the toolset as an escape hatch rather than a general-purpose tool. The explicit routing sentence naming list_project_items, get_code, and build_project makes it distinguishable from every relevant sibling without opening another 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 rule ('use this only when nothing else does'), an explicit when-not rule (prefer a dedicated tool when one fits), a caution threshold ('pause before running anything that quits the IDE or touches the shell'), and a hard boundary with a pointer to the correct alternative ('It cannot delete project items... see create_project_item'). This is about as complete as usage guidance gets.

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 real behavioral context beyond that: the success string, that compile errors are returned but runtime exceptions are invisible and must be asked of the user, a 30-second wait cap, and the prerequisite that the IDE must be running with the project open. That is the full burden carried well.

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

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

Front-loaded with the action and the primary guard, then prerequisites last. It is dense with several sibling references, but each sentence carries distinct decision-relevant information; only the runtime-exception aside is mildly verbose.

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

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

No output schema exists, and the description compensates by describing both return cases (launch confirmation vs. compile errors) plus the invisible runtime-exception gap. Prerequisites and the wait limit round out everything 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?

Zero parameters, so the baseline of 4 applies; there is no parameter semantics to explain and the description correctly spends no space on them.

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 ('Runs the open Xojo project in the IDE's debugger'), which is precisely distinguishable from build_project (compile only) and agentic_run (Agentic Mode compile-error reporting). An agent knows exactly what this does without opening the schema.

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

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

Explicitly constrains invocation ('Call it only when the user asks to run') and names alternatives with the condition that selects them: agentic_run for Agentic Mode projects, debug_control to step, stop_project to end. This is textbook when/when-not/alternatives 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 flag destructiveHint=true and idempotentHint=true, and the description adds the concrete consequences behind that: disk files are overwritten, edits made on disk can be lost in one specific ordering, the IDE must be running with the project open, and the exact return strings including the two-second no-change window.

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

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

Three sentences, each doing distinct work: mechanism, when to call, when not to call, plus a precondition. It is dense rather than padded, though the precondition about the IDE running could have been folded into the opening sentence for tighter front-loading.

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

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

For a zero-parameter mutation with no output schema, the description covers mechanism, preconditions, return values, and the dangerous ordering relative to revert_project — everything an agent needs to call it 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 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 plus the exact mechanism: writes the IDE's in-memory copy over the project's files on disk. This clearly distinguishes it from sibling write tools like set_code, edit_code, or revert_project that touch either memory or disk alone.

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 (after IDE-side edits from set_code/edit_code/create_project_item should persist, and before editing on disk a file changed through the IDE), explicit when-not (never between a disk edit and revert_project, since it would overwrite the disk edit), and it names the sibling that plays the alternative role.

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 idempotentHint=true, so the safety profile is known, but the description still adds real behavioral detail beyond them: the tool writes nothing and must be followed by manual insertion, it normalizes visibility keywords against Flags, escapes the constant's Default value, and applies IDE-style indentation. It also defines failure modes (inapplicable argument for block_kind, non-identifier name, unescapable constant value), which no annotation covers.

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 and the block-kind enumeration before the procedural insertion guidance, so an agent can stop reading early. It is dense rather than padded, though the clause about usage-guide.md Format Rules and placement before #tag ViewBehavior adds length that a pointer could have compressed.

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

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

With no output schema, the description carries the return-value burden, and it does so by stating the result is text only and describing what a control_event result contains. It stops short of showing the returned block's shape (headers, Flags line layout) or noting whether the text includes surrounding delimiters, which is the remaining gap for a text-generating 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 would be 3; the description adds cross-parameter semantics the schema cannot express — that control_event yields an entire #tag Events block, and that only its inner Event/EndEvent portion should be pasted when one already exists, plus the general rule that arguments not applying to block_kind are errors. The individual per-parameter meanings still live in the schema rather than the description, keeping it below 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?

The description gives a specific verb ("Generates") plus a precisely enumerated resource: a #tag block for a .xojo_code or .xojo_window file, with the seven supported block kinds listed inline. An agent can distinguish it from siblings like edit_code or set_code because it is explicitly a text-generating, no-side-effect scaffolder rather than a file mutator.

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

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

It states the use case explicitly (use instead of writing #tag syntax from memory when editing a project file on disk) and names the follow-up sibling, lint_project_file, for verification. It also states the exclusions: it only returns text, the caller must insert it, and it reads no files and needs no IDE — leaving nothing about when-to-use to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantial context beyond them: results are unranked document order, excerpts carry section titles and '>>>' markers, multi-word queries must appear verbatim, and the tool reads installed docs and fails if none was found. This is exactly the behavioral detail an agent needs before invoking it.

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

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

Front-loaded with the core action and search semantics, followed by return format, query guidance, sibling routing, and environment requirements. Every sentence contributes a distinct operational fact with no filler.

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

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

With no output schema, the description fully explains the return shape (ordered excerpts, section headings, marked matching lines) and the no-match case. It also covers the environment prerequisite, leaving nothing material for an agent to guess.

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: query is a verbatim literal substring, multi-word phrases must match exactly, and max_results governs excerpt count. It says nothing extra about context_lines, which is left entirely to the schema, so it falls just short of a 5.

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

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

States a specific verb and resource ('Searches the full text of the local Xojo documentation') plus the exact matching semantics (case-insensitive literal substring). It explicitly distinguishes itself from the sibling lookup_class, so an agent can choose between them 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?

Gives explicit when-to-use cases ('concepts, how-tos, error messages, or a class whose name you are unsure of') and names the alternative with its selecting condition ('when you know the name, lookup_class returns its reference page directly'). It also preempts a common misread by saying 'No match is a normal result, not an error.'

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the bar is lower, yet the description adds real behavior: it mutates only IDE selection state, not the project, and a nonexistent path errors by naming where the IDE actually is, which doubles as spell-check feedback. It does not spell out what the return payload contains beyond 'where the IDE landed and its type'.

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

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

Three sentences, each carrying distinct load: what it does, its error affordance, its selection-only scope, then the routing list and prerequisite. Dense but front-loaded and free of filler; only the enumerated sibling list runs long relative to a one-parameter tool.

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

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

For a single-parameter, non-destructive tool with no output schema, the description covers action, return shape, error behavior, state-mutation scope, prerequisite, and the exact sibling contexts it serves. Nothing an agent needs in order 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% and already carries the dot-separated path examples, so the baseline is 3. The description adds failure semantics for the parameter (nonexistent path → error naming the current location) and echoes the path form, giving modest value 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+mechanism: selects an item in the Xojo IDE Navigator by dot-separated path, and returns where the IDE landed plus its type. It also distinguishes itself from the large sibling set by naming the tools that select their own location instead of relying on this one.

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 routing rule: tools that take a location select it themselves, so this is for those acting on the current item, with four named callers (get_selected_text, set_selected_text, analyze_project with scope 'item', create_project_item without parent_location). Prerequisite ('Xojo IDE running with the project open') is stated outright.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real context beyond that: everything the item held is overwritten, failures write nothing, the change lives only in the IDE until save_project, and the Xojo IDE must be running with the project open. That is exactly the operational detail an agent needs before a destructive write.

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

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

Front-loaded with the core action and scope, and every following sentence carries information (alternatives, error behavior, persistence, prerequisite). It is dense and somewhat run-on with stacked clauses, but none of the content is filler.

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

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

For a destructive two-parameter write tool with no output schema, the description covers prerequisites, failure semantics, what is destroyed, what is out of scope, and how the change persists. 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% and already documents both parameters, so the description only needs to add meaning. It does add a useful cross-reference (the path format is the same as get_code, and it reaches the same items), but it does not expand on the code payload beyond what the schema states.

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

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

States a specific verb (replaces) and resource (the whole code of one method/event handler/code item) with scope (in the open Xojo project). It explicitly distinguishes itself from edit_code and set_declaration, so an agent can separate the three without opening any schema.

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

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

Names the alternatives and the conditions that select them: use edit_code for a change to existing code, set_declaration for name/parameters/return type. It also states when the tool is not appropriate (nonexistent path, item with no code editor) and what follow-up call is needed (save_project).

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds real context beyond them: 'Every field is replaced, so pass the current values of those you are keeping', the 'OK: <location>' return value, the named error cases, and that the change stays in the IDE until save_project. That is exactly the behavioral disclosure an agent needs before invoking 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-loaded with the action and the sibling relationship, and every sentence carries distinct information (semantics warning, replace-all behavior, return value, error cases, save requirement). It is dense but not padded; the packed NOTE sentence is the only mild readability 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 six-parameter destructive mutation with no output schema, the description covers the return value, failure modes, persistence semantics, the create_project_item workflow, and the environment prerequisite. 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 baseline is 3, but the description adds genuine semantic disambiguation with the NOTE that `parameters` and `data_type` swap meaning between a method and a property — the most likely source of a mis-call. It reinforces rather than merely repeats the schema.

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

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

States a specific verb (Sets) and the exact resource (name, type, scope, parameters of the current method or property) in the Xojo IDE. It also positions itself relative to create_project_item, so an agent can distinguish it from sibling tools like set_code or create_project_item without opening a schema.

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

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

Gives clear context: it is the second half of the create_project_item flow ('DoCommand "NewProperty" creates a blank, untyped property, and this is what names and types it'), and it names a hard exclusion (constants or other item kinds are refused) plus the prerequisite that the Xojo IDE must be running with the project open. It does not explicitly route to a sibling for the 'change existing code' case, keeping it just 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 flag destructiveHint=true and idempotentHint=false, but the description adds real value: the edit stays in the IDE until save_project, the IDE must be running with the project open, and it fails when no code editor is active. Doesn't describe the return value, but no output schema exists so this is a minor gap.

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 primary behavior is front-loaded in the first sentence, followed by parameter behavior, alternative tool, and prerequisites. Every sentence carries actionable information with no filler.

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

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

For a 3-parameter mutating tool with full schema coverage and no output schema, the description covers behavior, selection semantics, alternative tools, prerequisites, and persistence. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by explaining the two modes (pass selection_start to select a range, otherwise act on the current selection), reinforcing the offset-vs-selection semantics.

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

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

States a specific verb and resource ('Replaces the selection in the Xojo IDE's code editor with text') plus the fallback behavior when nothing is selected. It is clearly distinguishable from siblings like set_code and edit_code.

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

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

Explicitly names the alternative ('edit_code is more reliable because it does not depend on offsets') and the condition that selects it (content-describable change vs offset-based). Also states prerequisites and the failure condition.

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

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

Goes well beyond the annotations by warning that unsaved work in the running app is lost outright and that the same confirmation string is returned regardless of whether anything was running. The prerequisite on the IDE adds operational context. It does not state the failure mode when the IDE is not running, which keeps it from 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?

Three tight sentences, each covering a distinct need: what it acts on, the data-loss consequence, the return value, and the prerequisite. Front-loaded with the action rather than preamble.

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

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

For a zero-parameter tool with annotations already declaring destructive/idempotent behavior, the description supplies everything else an agent needs: the causally linked sibling, the irreversibility, the constant return value, and the environment prerequisite.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter 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 concrete verb and resource ("Ends the Xojo IDE's debug session by killing the app it is running") and ties the resource to the sibling calls that started it (run_project, agentic_run). An agent can distinguish this from run/build tools without opening the schema.

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

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

Gives clear context for when this applies (after run_project or agentic_run) plus the prerequisite that the IDE must be running with the project open. It stops short of explicitly distinguishing itself from the sibling debug_control, which an agent could reasonably consider for stopping a session, so it is 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.