Local MCP

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses meaningful behavioral semantics: reading marks messages as DELIVERED, acknowledgment is the only indicator of session-level read status, ack does not imply agreement or action, and agent messages never substitute for user approval. This adds substantial context that annotations alone do not 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?

Every sentence earns its place: purpose, timing, delivery-vs-read meaning, semantic boundaries, and a safety caveat. The description is front-loaded with the tool's core action and keeps the explanation tight without 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?

Given the output schema exists and the parameters are fully documented in the schema, the description covers everything needed for correct invocation: when to call, what to pass, what the acknowledgment semantically means, and an important caveat about agent messages. There is no material gap for an agent to call this tool correctly.

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

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

The input schema already provides full descriptions for both parameters: agent_id is the same one used in agent_checkin, and message_ids are the IDs returned by agent_inbox. The description only repeats 'passing the message_id of each one', so it adds no meaning beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: it tells senders that the agent actually read messages from agent_inbox. It clearly distinguishes acknowledgment from delivery and from agreement/action, and it differentiates this tool from the inbox-reading sibling by explicitly stating what agent_ack alone accomplishes.

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

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

It gives explicit timing guidance: call it right after reading messages, passing each message_id. It also clarifies the delivery-vs-read distinction and why this call is necessary. It does not name explicit alternatives or negative conditions, but the context is clear enough that an agent would know when to invoke it.

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

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

Annotations mark it as non-read-only and open-world; description elaborates on the side effects: entry expiry, disappearance if not checking in, and the renew-on-call behavior. It reveals the auto-wake integration without contradicting any annotation.

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

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

The description is long but each sentence carries information; it's front-loaded with the core purpose and then provides necessary details. No filler, though it could be trimmed slightly without losing value.

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

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

With a rich schema, output schema, and detailed description covering when, how, and side effects, an agent has everything needed to call correctly, including prerequisites and nuances like TTL defaults and auto-wake behavior.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds default TTL logic based on role, updates status guidance, and explains herdr_pane purpose, adding meaning beyond the schema's short examples.

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 (announces) and resource (the mesh), and clarifies the session's role, repo, and capabilities. It distinguishes from siblings like agent_inbox and agents_list by focusing on registration/presence.

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 instructs when to call (start of work, every few minutes) and explains the expiry mechanism and the dependency on agent_inbox. It also mentions the auto-wake behavior for Herdr panes, giving clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral context: the return is data about other agents, not instructions, and should never replace user approval. This goes well beyond the annotations and is essential for correct use.

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 four sentences with zero waste. It front-loads the purpose, then gives usage timing, then an important behavioral warning. Each sentence earns its place.

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

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

For a simple read tool with two parameters, an output schema, and safety annotations, the description covers purpose, usage timing, and the critical behavioral caveat. 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% — both parameters are already documented. The description adds minimal value beyond the schema: it ties agent_id to the one used in agent_checkin, which is useful but not extensive. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description clearly states the verb (reads), the resource (messages other agents sent), and the scope (since last poll). It distinguishes itself from sending tools and names a prerequisite (agent_checkin), so an agent can tell it apart from siblings like agent_send.

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 when to poll (start of task and periodically during long work) and gives concrete examples of what it reveals. It also instructs to check in first with agent_checkin. It doesn't explicitly list alternatives, but the context implies this is the receiving side, so guidance is clear though not exhaustive.

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

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

Beyond the annotations, the description reveals an important behavioral trait: calling it twice does not replace an existing mesh but returns the existing one. This materially shapes an agent's expectations and is more than the annotations alone 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?

Three tightly written sentences, each earning its place: what the tool does, when to use it versus the join sibling, and what happens on repeated calls. The key scoping fact is front-loaded.

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

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

For a one-parameter tool with an output schema and sibling guidance, the description covers selection, invocation, placement in the mesh lifecycle, and idempotency. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, and the single optional label parameter is already well described in the schema as the human name for this machine. The description adds no new parameter detail, so the baseline of 3 is appropriate.

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

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

States a precise verb and resource: 'Starts a new agent mesh with THIS machine as its first member.' It explicitly differentiates itself from agent_mesh_join, so an agent can distinguish it from the closest sibling without inspecting other schemas.

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

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

Gives explicit usage context: use once on the user's first machine, and every other machine should use agent_mesh_join instead. Also clarifies the idempotent second-call behavior, so no ambiguity remains about repeated invocation.

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 indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds valuable behavioral context: the code is single-use, expires in 15 minutes, and enrollment is deliberately manual. This goes beyond what annotations provide and helps the agent understand the operational implications.

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 the tool does, how to handle the output, and a critical behavioral caveat. The most important information (single-use, 15-minute validity) is front-loaded, and the manual-enrollment warning is placed at the end as a clarifying note.

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 an output schema, the description is complete. It explains the tool's role in the mesh enrollment flow, the code's properties, and the manual-enrollment constraint. An agent has everything it needs to decide when to call this tool and what to do with 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?

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining what the tool produces (a single-use pairing code) and its validity window (15 minutes). Since there are no parameters to document, the description fully covers the semantic space.

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 ('creates'), a specific resource ('single-use pairing code'), and a clear purpose (allowing another machine to join the mesh via agent_mesh_join). It also distinguishes itself from sibling tools like agent_mesh_create and agent_mesh_join by explaining the code's role in the enrollment flow.

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

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

The description explicitly tells the agent when to use this tool: to generate a code for another machine to join the mesh. It also provides a clear exclusion: 'having a cloud token does NOT put a machine in the mesh,' which prevents misuse. It names the complementary tool (agent_mesh_join) and instructs the agent to give the code to the user.

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 indicate this is a mutating but non-destructive operation. The description adds the enrollment effect and post-join capabilities, plus the source of the code via agent_mesh_invite. It doesn't cover permission requirements or reversibility, but the core behavior is transparent.

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

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

Three sentences with no waste: action + source, postcondition, and alternative. The essential task is stated first, and the sibling routing is at the end.

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

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

Given an output schema and complete parameter schemas, the description supplies the remaining context—what the machine gains from joining and how to create instead. An agent has everything needed to call it correctly.

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

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

With 100% schema description coverage, the schema already documents both parameters. The description reinforces the code's provenance ('from agent_mesh_invite') and clarifies label as 'THIS machine', a small but useful addition. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

States a specific verb ('enrolls') and resource ('existing agent mesh'), and explicitly names the sibling it is not ('To create a mesh instead of joining one, use agent_mesh_create'). An agent can tell it apart from agent_mesh_create without opening schemas.

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

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

Provides clear context: use when the user has a pairing code from agent_mesh_invite on another machine. Explicitly routes to agent_mesh_create for the create case, covering the main alternative. The reference to agent_mesh_invite also clarifies the prerequisite flow.

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 disclosing immediate effects: disappears from directory, stops receiving messages, and minted pairing codes die. It also states the action is not reversible from the other side, adding real operational context beyond destructiveHint.

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, front-loaded with the core action and immediate effects, followed by clear use cases and cautions. Every sentence contributes meaningful information without redundancy or 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?

Comprehensive for a revocation tool: it covers what happens, when to use it, user consent, irreversibility, and the path to re-invite. With an output schema and full parameter documentation available, nothing important is missing.

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

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

The input schema fully documents the single 'handle' parameter and already explains it is the machine to remove and where to get it from ('agents_list'). The description adds no extra parameter-level detail, so the baseline for high schema coverage applies.

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

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

The description states a specific verb and resource: 'Removes another machine from this mesh', and immediately clarifies the scope and consequences. It clearly distinguishes this from sibling mesh tools like invite or join by focusing on removal and its effects.

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

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

Explicitly says when to use it: 'when a pairing code may have leaked, or when a machine should no longer see the user's other agents.' It also warns to ask the user first and notes the machine 'has to be invited again', indicating the alternative path after revocation.

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 and destructiveHint, so the safety profile is covered. The description adds behavioral context beyond that: it explains that the tool tells the agent whether to create or join a mesh, which is a decision aid that isn't captured by annotations. It doesn't repeat annotation info, which is appropriate.

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

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

The description is two sentences with no filler. The first sentence defines the tool's core function, and the second delivers usage guidance. Every word earns its place, and the critical instruction to use it first is front-loaded.

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

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

For a parameterless status tool with an output schema, the description fully covers what the agent needs: it explains what the tool does, how it fits into the workflow, and what actions to take based on the result. The output schema handles return format, so nothing is missing.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. According to the baseline for 0 params, a score of 4 is appropriate because there is no parameter information to add, and the description doesn't need to explain any.

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

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

The description states a clear, specific purpose: it shows whether the current machine belongs to an agent mesh, and defines what a mesh is. It distinguishes itself from sibling agent_* tools by positioning it as the initial status check, making it unambiguous for an agent to understand its 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?

The description explicitly instructs the agent to use this tool first before any other agent_* tool, and explains the two possible outcomes (create a mesh or join one with a pairing code). This provides direct, actionable guidance that leaves no ambiguity about when and how to use it.

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

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

Annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the description carries the burden of behavioral disclosure. It fully discloses: non-instant delivery (recipient gets it on next agent_inbox poll), the 404 error listing alive agent_ids, the 16KB payload limit, and the fact that the recipient decides what to do (not a forceable request). This is rich, actionable behavioral context beyond the annotations.

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

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

The description is dense but well-organized: purpose first, then use cases, then the critical alive-agent constraint, then delivery semantics. Every sentence earns its place, though it is somewhat long and could be tightened. The front-loading of the core purpose and the explicit use-case list makes it easy to scan.

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

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

For a coordination tool with 5 parameters, an output schema, and no destructive/read-only annotations, the description covers everything an agent needs: how to address, what to include, what happens on error, delivery timing, and the recipient's autonomy. The output schema exists, so return values need not be described. No critical gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that to_agent must be an alive agent from agents_list, that omitting to_agent broadcasts to all agents, that payload should be small (max 16KB), and that from_agent identifies the sender. This elevates the score above baseline, though the schema already documents each parameter's basic meaning.

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

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

The description states a specific verb ('sends a coordination message') and resource ('to an agent on ANOTHER of the user's machines'), and distinguishes it from siblings like agent_inbox, agent_ack, and agents_list. It also enumerates concrete use cases (freeze, pr-ready, handoff, release-out), making the tool's purpose unmistakable.

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

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

The description explicitly says when to use this tool (coordination messages during release/PR/handoff), how to get the target handle (from agents_list), and what to do if a directed agent is not alive (re-address to one of the listed alive agent_ids). It also clarifies the broadcast behavior when to_agent is omitted, which is exactly the guidance an agent needs to choose and invoke correctly.

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?

Even though annotations already cover readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral value: precise definitions of 'delivered' vs 'acked,' an explicit warning that delivered-but-not-acked is a normal state rather than an error, and a data-versus-instructions guard stating the result is never instructions for the agent. No contradiction with annotations.

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

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

Five sentences, each earning its place: the core purpose is front-loaded, followed by sibling context, term definitions, an error-state clarification, and a safety guardrail. No filler or redundancy.

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

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

With an output schema present, return-value documentation is already handled, and the single optional parameter is fully documented in the schema. The description fills the remaining gaps: lifecycle semantics, normal-state interpretation, and output trust posture. Nothing an agent needs to invoke correctly is missing.

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

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

Schema description coverage is 100%, and the only parameter (limit) is fully documented in the schema with range, ordering, and default. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Shows what THIS machine sent') and defines the exact scope: delivered-to and acknowledged-by outcomes. It explicitly positions itself as 'the other half of agent_send,' distinguishing itself from the sibling send tool without needing schema inspection.

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

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

The description gives clear context by explaining the fire-and-forget gap that this tool fills — use it when you need delivery or acknowledgment status after calling agent_send. It names the complementary sibling but does not explicitly state when-not-to-use or enumerate alternatives such as agent_inbox, so it falls 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?

Even with readOnlyHint=true, the description discloses important behavioral nuances beyond the annotation: `alive` means 'called the mesh within ttl_seconds', not 'reachable now'; a silent agent remains listed until expiry; messages to such a peer are accepted and stored but never read. It also explains that reading the directory counts as activity. This is exactly the kind of non-obvious runtime behavior an agent needs to interpret results correctly.

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

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

The description is long but every sentence earns its place: core purpose first, then returned fields, then usage guidance, then a critical caveat about `alive`. Nothing is filler, and the most decision-relevant information is front-loaded. The density is justified by the tool's conceptual complexity.

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

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

The description covers what the tool does, what each returned field means, how to interpret staleness, when to call it, how to use its output, and the side effect of calling it. With an output schema present and only two optional self-describing parameters, no essential operational detail 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?

Although schema coverage is 100%, the description substantially enriches both parameters. It explains that passing `agent_id` renews the caller's presence and that omitting it means nobody is renewed, and it clarifies the semantics and default of `include_stale`. This goes beyond the schema descriptions and helps an agent decide whether or not to pass each parameter.

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

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

The description names a specific verb and resource: listing agents across all user's machines in the mesh. It enumerates the exact fields returned (machine, role, repo, capabilities, status, status_age_s, last_activity_at, expires_at), so an agent knows precisely what this tool produces. It also implicitly differentiates itself from messaging siblings by explaining it is the source for the `handle` used to address an agent.

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

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

The description gives explicit, concrete when-to-use guidance: check it before heavy work such as a release, refactor, or deploy; use `status` + `last_activity_at` to distinguish working peers from stuck ones; use it to get a peer's handle; and re-run it before concluding a peer is unresponsive because its entry may have expired. It also mentions the related action `agent_send` in the intended workflow.

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 supply the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds genuinely behavioral context: a license requirement, a two-phase preview-then-confirm gate, and the ambiguity that a matching task_name completes only the first match found. It also states what is returned, which is more than the annotations carry.

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

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

Front-loaded with the action, then prerequisites, then routing guidance. Five compact sentences with little waste; the closing sentence about the return value is marginally redundant given an output schema exists, but it carries rationale (telling the user which task was completed).

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 mutation tool with an output schema, the definition covers everything an agent needs: prerequisites, id-vs-name selection, ambiguity behavior, the confirm gate, and what the call returns. 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?

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by stating the preference order between task_id and task_name, the exact-match requirement, and the first-match-only consequence of using task_name.

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 ("Marks an OmniFocus task as complete") and implicitly differentiates from the many sibling completion tools (todoist_complete_task, todo_complete_task, complete_reminder) by naming the OmniFocus domain and its list/search siblings. An agent can route to it without opening a schema.

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

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

Explicitly tells the agent to prefer task_id sourced from list_omnifocus_tasks or search_omnifocus_tasks, describes the fallback condition (when you don't have the id) and the exact-match/first-found caveat, and gates execution behind confirm=true with a preview otherwise. Prerequisite (OmniFocus Pro) is also stated.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, already conveying mutation without destruction. The description adds a meaningful guardrail by stating that confirm=true is required before the action will execute, which is a behavioral constraint beyond the structured annotations.

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

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

The description is two short sentences with the action front-loaded. Every phrase earns its place: the platform, the mandatory confirm flag, and the pointer to the To Do alternative. No redundancy or 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 simple two-parameter mutation tool with a full output schema and annotations, the description covers the essential context: platform, required confirmation, and a cross-platform alternative. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'Requires confirm=true' reinforces the confirm parameter, and 'Reminder ID from list_reminders' in the schema already documents the ID source. No additional parameter meaning is provided beyond the schema.

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

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

The description uses a specific verb and resource: 'Marks a reminder complete in Apple Reminders (Reminders.app).' It also distinguishes itself from the sibling tool 'todo_complete_task' by directing Microsoft To Do users there, making the tool's scope unambiguous.

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

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

The description explicitly states 'Requires confirm=true' as a usage prerequisite and gives a clear alternative: 'For Microsoft To Do use todo_complete_task instead.' This tells the agent exactly when to use this tool versus a related sibling.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context beyond them: the default is a non-mutating preview, the write is gated on confirm, configs are edited rather than authored by hand, and the restart/new-session requirement for changes to take effect. It also enumerates the four per-client outcome states the agent should expect.

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

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

Purpose and scope are front-loaded in the first clause, and the sentences carry substantive information (gating, outcomes, restart step). The parenthetical client catalog is somewhat redundant with the schema's id enum, but the overall density is high and little is wasted.

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

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

For a two-parameter, conditionally-mutating tool this is complete: the agent knows the default preview behavior, how to commit changes, how to scope to a single client, what the response will signal per client, and what follow-up action the user needs. The output schema already covers return structure, so the description's per-client summary is complementary rather than required.

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

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

Schema description coverage is 100% and both parameters are fully documented there (including the enumerated client ids and the 'omit to do all installed' behavior), so the description's mention of an optional single `client` id and the preview/confirm gate largely restates structured data. Baseline 3 is appropriate; the description adds no syntax or format detail the schema lacks.

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 (adds/configures) and resource (Local MCP entries in MCP-capable app configs), names the source catalog and example clients, and explicitly contrasts with 'manual JSON editing'. An agent can immediately tell this is the tool that wires LMCP into other apps, distinct from lmcp_install_upgrade or setup_install.

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?

Clearly states the trigger conditions: it writes only when confirm:true, otherwise it is a read-only preview, and it optionally narrows to one client. It also routes the agent to a companion step ('Pair with list_missing_permissions for fully agent-driven setup'), though it does not describe when NOT to use it or profile side effects of repeated runs.

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 disclosing that this is a two-phase, out-of-band flow requiring the user to visit a URL between calls, that the channel-message permission is gated on tenant-admin approval, and that a refused sign-in leaves the account's existing access intact (reinforcing non-destructive behavior). These are the details an agent needs to sequence the call correctly.

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

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

Three tightly packed sentences with no filler: purpose first, then the two-call procedure, then the optional flag and its gating condition. The critical operational detail (second call required after external authentication) is front-loaded rather than buried.

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

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

For a single-optional-parameter connection tool with an output schema available for return values, the description covers everything the agent needs: the multi-step sequencing, the out-of-band authentication requirement, and the admin-approval gate. 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?

Schema description coverage is 100%, so the schema already fully documents include_channel_messages. The description's treatment of the flag is essentially a restatement of the schema text, adding no syntax or format detail beyond it. Baseline 3 applies when the schema carries the 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 ('Connect a Microsoft 365 account') and immediately covers the related cases of adding an additional account or re-authenticating an existing one. An agent can distinguish this from siblings like disconnect_m365_account or list_m365_accounts without opening any schema.

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

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

Gives an explicit procedure: call once to obtain a login code, then call again after authenticating at microsoft.com/devicelogin. It also states the prerequisite (administrator approval) for the channel-messages permission. It stops short of naming alternative tools for other account operations, but the when/how guidance is clear.

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

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

The description adds valuable behavioral context beyond the annotations: credentials are entered directly in Local MCP's settings window and never passed through the AI, and the tool returns a link rather than accepting credentials directly. This is important for safe usage and is not expressed by the schema or annotations.

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

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

The description is short and front-loaded, with the key behavioral note about security placed in the second sentence. The opening phrase 'Connect ServiceNow' is somewhat redundant with the title, but the rest of the description is efficient and every sentence contributes actionable guidance.

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

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

For a zero-parameter setup tool with an output schema and annotations, the description is complete enough: it tells the agent what action to take, what link to expect, and how the user should complete the connection. It does not explain post-connection status, but the output schema can cover return details.

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

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

The tool has zero parameters, so the baseline is 4. The description reinforces this by explaining that the user enters credentials in a separate settings window, not through the tool call. This helps prevent the agent from prompting for credentials or fabricating parameters.

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

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

The description states a clear verb and resource: connect to ServiceNow, and explains the immediate outcome (get a link). It does not explicitly contrast with sibling connection tools like connect_chatgpt or disconnect_servicenow, so it loses a point on differentiation, but it is unambiguous about what this tool initiates.

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

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

The description gives explicit usage steps: call this to get the link, then open it and enter instance, username, and password. It clearly communicates when to use the tool and what the user must do afterward, though it does not mention alternatives or exclusion criteria such as using disconnect_servicenow to undo the connection.

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

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

The description adds important security context: the API token is entered directly in Local MCP's settings and never passed through the AI. It also clarifies the tool's behavior (returns instructions or connection status), going beyond the minimal annotations.

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

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

The description is two sentences, front-loaded with the tool's purpose, and includes a valuable security note without any fluff. Every sentence earns its place.

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

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

For a tool with no parameters and an output schema, the description is complete: it states what the tool does, when to call it, and a critical security behavior. No important context is missing.

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

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

The tool has zero parameters, so the schema is trivially 100% covered. The description appropriately describes what the tool does instead of parameter details, meeting the baseline for no-parameter tools.

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

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

The description clearly states the tool's purpose: to get instructions for connecting Todoist or check if it's already connected. This distinguishes it from sibling tools like disconnect_todoist and todoist_* task management tools.

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

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

It explicitly says 'Call this to get the instructions, or to check whether Todoist is already connected,' giving clear guidance on when to use it. It does not mention alternatives, but the context makes them obvious.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: attendees only work on CalDAV/Exchange calendars, and recurrence supports the four period types. It does not mention the confirm flag required to actually create the event, which is a notable behavioral rule left to the schema.

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

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

Four tight sentences, front-loaded with purpose, then requirements, then optional capabilities, then the alternative-tool routing. No filler; each clause carries distinct, actionable information.

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

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

With annotations and an output schema present, the description needn't explain return values, and it covers the creation scope, required fields, and key constraints. It omits the confirm flag and calendar_id defaults, but those are fully specified in the 100%-covered schema, so coverage is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters in depth (timezone rules, all-day conventions, mutual exclusivity). The description restates only a few (recurrence values, attendees) and adds little beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Creates an event in the Mac's Calendar app') and scopes it to Calendar.app, distinguishing it clearly from update_calendar_event and list_calendar_events. It also explicitly names the sibling it is not (m365_create_event) for the Microsoft 365 case.

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

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

Names the alternative ('For Microsoft 365 use m365_create_event instead') with the exact condition that selects it, and states the required inputs plus the option to invite attendees or set recurrence. Routing is unambiguous without opening either schema.

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: discloses the plain-text quote format ('On <date>, <sender> wrote:' with '> ' prefixes), that html_body is downgraded to plain text in replies, the meaning of quoted_original, and the three-state threaded value including a relay-the-warning instruction. The confirm=true gate (preview without it) is a genuinely important behavioral disclosure for a mutation tool.

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 key constraint ('never sends') and organized around new vs reply flows, but it is a dense multi-sentence block and some response-field detail could be trimmed given an output schema exists. Every sentence still carries substantive information.

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

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

For a 12-parameter tool with an output schema, the description covers the decision paths (new vs reply), the confirm gate, account targeting, attachments, and the threading caveats. 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 baseline is 3, but the description adds real meaning: it groups parameters into new-draft vs reply-draft usage, clarifies account-vs-from as alternatives, notes subject is ignored in replies, and specifies the attachments path format. Only minor syntax detail is left to the schema.

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

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

States a specific verb (saves a draft) and resource (Mail.app Drafts folder), and immediately differentiates from send_email/reply_email by asserting 'it never sends.' An agent can tell it apart from the send siblings 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 clear context: new draft via to/subject/body vs reply draft via reply_to_message_id/reply_all, plus the cautious-user scenario. It does not name send_email or reply_email as the explicit alternatives for when the user actually wants to send, so the routing is implied rather than stated.

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

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

Annotations only supply readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds substantially more: refusal to guess the target account, idempotent no-op when the folder already exists, and verification against the account's folder list before reporting success. These are exactly the traits an agent needs before issuing a 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?

Four sentences, front-loaded with the core action and then the constraints; each sentence carries a distinct rule (account requirement, idempotency, verification, confirm gate). Slightly dense but nothing is redundant.

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

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

For a 3-parameter mutation with an output schema already present, the description covers everything needed: target scope, conditional parameter requirement, idempotency behavior, verification of success, and the preview/commit gate. No significant gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the terse schema text: `account` becomes conditionally required rather than merely 'optional, uses default', and `confirm` false/omitted is documented as a preview mode rather than just 'must be true to create'.

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 with scope: creates a mailbox folder in the Mac's Apple Mail, in exactly one account. An agent can distinguish this from list_email_folders and from m365/Outlook folder tools without opening a schema.

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

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

Explicitly states when `account` is required (multi-account setups) and names list_email_accounts as the way to discover names, plus a clear when-to-pass-confirm rule (omitted = preview, confirm=true = create). Alternatives and conditions are spelled out rather than inferred.

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

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

The description adds meaningful behavior beyond the annotations: it discloses that Markdown is converted to Apple Notes native formatting, and that no action occurs unless confirm=true. This is valuable because the confirm gate is a behavioral requirement an agent must know before invoking. The behavior is consistent with readOnlyHint=false and destructiveHint=false, so there is no contradiction.

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 with the core purpose. It includes only a short list of supported Markdown features and the crucial confirm requirement. It earns a 4 rather than 5 because the Markdown details duplicate the schema and could be trimmed, though nothing is truly wasteful.

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

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

For a creation tool with full schema coverage, an output schema, and clear annotations, the description covers the essential decision points: what the tool does, target system, formatting behavior, and execution gate. It does not explicitly discuss return values or failure behavior, but the existing output schema reduces the need for that.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description mostly echoes schema content, such as Markdown support in body and the confirm default behavior, without adding new parameter-level meaning. Baseline 3 is appropriate because the schema carries the parameter-semantics load.

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

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

The description opens with a specific verb and resource: 'Creates a new note in Apple Notes.' This clearly distinguishes it from sibling tools like read_note, update_note, delete_note, and search_notes. Naming Apple Notes explicitly prevents confusion with other creation tools such as create_reminder or create_draft.

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

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

The context is clear: this tool is for creating notes in Apple Notes, which is sufficient to route an agent to it versus read/update/delete/search siblings. It also gives an important usage rule: 'Requires confirm=true to execute.' However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses a capability prerequisite (Pro tier blocks automation), a hard failure mode (no project-name fallback, error instead), and a safe preview/confirm gating behavior. These are exactly the behavioral traits an agent needs before mutating state.

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

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

Five tight sentences, front-loaded with purpose and prerequisite, then the failure mode, then the confirm workflow, then the return value. No filler and every clause carries actionable information.

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

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

For a 7-parameter mutation tool with an output schema, the description covers prerequisites, defaulting behavior, error conditions, and the confirm gate, and even notes the return value. Nothing material is left for the agent to infer.

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 a 3 is the baseline. The description adds genuine meaning beyond the schema for two parameters: `project` must match an existing project name exactly or the call errors, and `confirm` toggles preview versus creation. It does not add detail for dates or `flagged`, but the added semantics lift it above baseline.

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

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

States a specific verb (creates) and resource (task in OmniFocus) plus scope (on this Mac). An agent can distinguish this from sibling task creators like create_reminder or todoist_create_task because the target application is named explicitly.

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

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

Provides clear operational context: the OmniFocus Pro prerequisite, the inbox default when `project` is omitted, and the direction to check names with list_omnifocus_projects first. It does not explicitly contrast against sibling task-creation tools, but within the OmniFocus family the routing guidance is strong.

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 provide readOnlyHint=false and destructiveHint=false, meaning this is a write operation that is not destructive. The description adds that it only records invites and does not send anything, and that each returned link can be included in an email or message. This clarifies that no external communication is triggered, which is valuable beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action and result. It efficiently covers the non-sending behavior and the lang parameter without wasted words. Every sentence adds value.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers the key behavioral aspects relevant to an agent: what it records, what it returns, that it does not send, and how lang maps to the user's context. Nothing essential is missing for a correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of context for 'lang' (records the language of the invite) and 'recipients' (colleagues the user chose), but largely restates the schema descriptions. It does not significantly enhance parameter meaning beyond what the schema 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?

The description states a specific action ('Records referral invites'), the resource ('colleagues a user chose to invite'), and the outcome ('returns a unique referral link per person'). It also clarifies the purpose (to later see who installed or activated LMCP), distinguishing it from email-sending or listing tools. The verb and resource are unambiguous.

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

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

The description explicitly says 'It does not send anything itself', which sets a clear boundary against send-type tools (e.g., send_email). However, it does not name an alternative tool like list_referral_candidates or send_email, nor does it describe when to choose this over other referral-related tools. The exclusion is stated, but explicit alternatives are missing.

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

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

The description adds substantial behavioral detail beyond the annotations: without confirm=true it creates nothing and returns a preview, and a due_date without a time suppresses notifications. These are critical runtime behaviors that the annotations do not convey.

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

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

Three sentences, all information-dense and front-loaded. The main purpose comes first, followed by the two most important caveats. No filler or repetition.

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

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

Given the output schema and 100% schema coverage, the description covers the essential behavioral nuances an agent needs: confirmation semantics, preview behavior, and notification implications of due_date. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for confirm (preview vs. actual creation) and due_date (alarm behavior), which go beyond the schema's simple field descriptions.

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

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

The description clearly states a specific verb and resource: 'Creates a reminder in Reminders.app.' It also explains the preview-only behavior without confirm=true, which distinguishes it from related tools like update_reminder, complete_reminder, and create_reminder_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?

The description provides clear context for when to use the tool: creating a reminder in Reminders.app. It gives important usage guidance about confirm=true and due_date time handling, though it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations only declare the generic non-read-only, non-destructive profile; the description adds real behavioral detail beyond that — account placement (same account as the default list, usually iCloud), the case-insensitive duplicate failure mode, the two-phase preview/confirm flow, and the returned id. These are exactly the traits an agent needs and none are recoverable from the annotations.

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

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

Four compact sentences, front-loaded with purpose and account scope, then failure mode, then the confirm protocol, then routing. Every sentence carries information, though the final routing sentence could arguably live in the sibling's description instead.

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, non-destructive creation tool with an output schema, nothing material is missing: scope, failure conditions, the confirm protocol, and the returned id are all covered, and return-value detail need not be expanded since an output schema exists.

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 genuinely enriches both parameters: it explains that omitting confirm yields a preview rather than a creation, and that name is subject to a case-insensitive uniqueness check. That is meaning beyond the terse schema text 'Must be true to create'.

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 ('Creates a new list in Apple Reminders'), pins the target account, and distinguishes itself from the reminder-creating sibling by routing the agent to create_reminder for the follow-up step. An agent can tell this apart from create_reminder, rename_reminder_folder, and delete_reminder_folder without opening any schema.

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

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

Gives clear operating context: it fails on duplicate names (case-insensitive), and it explains the preview-vs-create gate. It also names the follow-up tool (create_reminder) for populating the list. What it lacks is guidance on the list-creation alternative path or when a preview call is preferable, so it stops short of full when/when-not coverage.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description usefully discloses that weather is included only when a location is provided, adding conditional behavior beyond the annotations.

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

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

Two tight sentences with the payload front-loaded and the conditional weather clause placed at the end. The closing 'Perfect for starting each day' is mildly promotional but still carries routing value.

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

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

An output schema exists, so return values need not be explained, yet the description still enumerates the brief's contents. For an aggregator with no required parameters, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already fully documented. The description only echoes the location-to-weather dependency, adding 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 a single morning briefing') and enumerates exactly what it aggregates: calendar events, overdue/due-today reminders, unread email count and subjects, and conditional weather. This cleanly distinguishes it from the many single-source siblings like list_calendar_events and list_reminders.

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?

Frames the use case clearly ('Perfect for starting each day: one call gives you everything on your plate'), which implicitly routes the agent here instead of making several sibling calls. It stops short of explicit when-not guidance or naming the individual tools it replaces.

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 destructiveHint=true, and the description adds meaningful destructive detail: deleting a recurring series via span='future', the default single-occurrence behavior, and the requirement to pass confirm=true. This tells the agent exactly what will be destroyed and what safety gate must be satisfied.

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

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

Three sentences with no wasted words. The action, requirement, recurring-event nuance, and sibling alternative are all included and front-loaded.

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

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

Given the nuanced recurring-event behavior, the description covers the key conditions, prerequisites, and alternative routing. The output schema covers return-value expectations, and the input schema fully documents parameters, leaving no material gap for an agent 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 adds value beyond the schema by clarifying the implications of span ('this and all following occurrences'), the source of event_id (from list_calendar_events), and the preview confirmation behavior. Some redundancy with the schema exists, but the extra context is helpful.

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: 'Deletes an event from the Mac's Calendar app (Calendar.app) by ID.' It also explicitly differentiates from the Microsoft 365 sibling by naming m365_delete_event as the alternative, so an agent can disambiguate without opening schemas.

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

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

It gives clear when-to-use guidance: use this for Calendar.app events, and use m365_delete_event instead for Microsoft 365. It also explains the required confirm=true precondition and the correct span values for recurring events versus the single-occurrence default.

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

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

Goes far beyond the destructiveHint=true annotation: it discloses the soft-delete semantics (Recently Deleted, 30-day purge, user-recoverable), the refusal behavior and its error code (note_already_deleted) that prevents permanent erasure, the Full Disk Access failure mode with trash_check: not_verified, and post-delete verification behavior. This is exactly the behavioral context an agent needs before firing a destructive call.

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 that is front-loaded with the core action and the recoverability guarantee before moving to edge cases. Every sentence carries weight for a destructive tool, though it is longer than strictly minimal.

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

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

Covers the operation, precondition, failure modes, recovery path, and verification guarantee; since an output schema exists it correctly avoids describing return payloads. An agent has everything needed to call this destructive tool safely.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it reinforces that confirm must be true to act, explains how to obtain note_id, and notes the title-collision risk ('first match is deleted'). It slightly duplicates schema text but the operational framing adds value.

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

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

States a specific verb and resource ('Deletes a note from Apple Notes, by ID or exact title'), which cleanly separates it from sibling delete tools (delete_reminder, gdrive_delete_file) and from update_note. An agent immediately knows the operation and the two addressing modes.

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 routing ('Find note_id with list_notes or search_notes'), an explicit when-not ('A note that is ALREADY in Recently Deleted is refused'), and a hard precondition ('Requires confirm=true'). Nothing is left to inference.

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

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

The description reinforces the destructiveHint=true annotation with 'Permanently deletes' and adds a mandatory confirmation guard ('Requires confirm=true'). This is valuable behavioral context beyond the annotations, though it does not detail failure modes or permission requirements.

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

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

Two concise sentences, each adding distinct value: the action and target, the ID source, and the confirmation requirement. No filler or redundancy.

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

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

For a simple destructive operation with a complete schema and output schema present, the description adequately covers the target, ID source, and confirmation gate. It could mention irreversibility more explicitly, but 'permanently deletes' already covers that.

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 covers both parameters fully (reminder_id as identifier from list_reminders, confirm as boolean that must be true), giving 100% schema description coverage. The description mostly restates this information, adding no new parameter-level 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?

The description clearly states the action ('Permanently deletes') and target resource ('a reminder in Apple Reminders by ID'). It also tells the agent where to get the required identifier, distinguishing it from related tools like update_reminder, complete_reminder, and delete_reminder_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?

The description provides concrete execution guidance: retrieve reminder_id from list_reminders and set confirm=true. It does not explicitly compare with alternatives or list exclusions, but the delete semantics are unambiguous given the sibling tool names.

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 destructiveHint=true, but the description adds significant context: it explicitly says 'cannot be undone' and that all reminders inside are deleted, which goes beyond just 'destructive'. It also specifies the confirmation requirement, making the irreversible behavior transparent. No contradiction with annotations exists.

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

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

The description is two sentences that front-load the action and critical warning, then provide usage details. Every clause adds value: what gets deleted, irreversibility, how to identify the target, and the confirmation gate.

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

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

Given the presence of an output schema, the description doesn't need to explain return values. It covers purpose, scope, irreversibility, identifier options, and confirmation requirement. It lacks only edge-case behavior like conflicting name and list_id, but those are outside typical expectations.

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 provides 100% coverage for all three parameters. The description reinforces the relationship between name and list_id as alternatives and points to get_reminder_folders as the source for list_id, adding a small sourcing hint. However, it mostly repeats schema information, so it meets but doesn't exceed the baseline for schema-covered params.

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

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

The description clearly states the tool deletes an Apple Reminders list and all reminders within it, using a specific verb and resource. It distinguishes itself from sibling delete_reminder by emphasizing the cascading deletion and irreversibility.

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

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

The description provides clear context: this deletes an entire list, not just a single reminder, and cannot be undone. It instructs the agent to pass a name or list_id (sourced from get_reminder_folders) and requires confirm=true. While it doesn't explicitly name alternative tools like delete_reminder, the cascade warning implies when this is appropriate.

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: discloses that it runs immediately with no preview or confirm step, that the default-account role is reassigned to the oldest remaining account, and that reconnecting requires re-authentication. These are exactly the behavioral traits an agent needs before invoking a disruptive operation.

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

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

Front-loads the core action, then layers scope, parameter rules, side effects, and environment constraint. Every sentence carries distinct 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?

Given an output schema exists, return values need not be detailed, and the description still notes the answer reports the new default. Covers single-parameter semantics, side effects, confirmation behavior, and the local-only constraint, leaving no gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies the accepted identifier forms (email/upn, id, display name) and the conditional optionality (omittable with one account, required with several), which sharpens how the agent should populate the field.

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 ('Disconnect ONE Microsoft 365 account and remove its stored sign-in') with clear scope ('ONE'), distinguishing it from the connect_* and set_default_m365_account siblings. An agent immediately knows what the tool does.

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

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

Gives explicit conditional usage for the account parameter ('with only one account connected it can be omitted, with several it must be given') and warns that reconnecting requires the sign-in flow again. It does not name sibling alternatives (e.g., set_default_m365_account, list_m365_accounts), so it stops short of a full when/when-not routing.

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

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

Discloses meaningful behavior beyond the annotations: stored credentials are removed, the action is immediate with no confirm step, and reconnecting will require the user to re-enter credentials. This gives the agent a clear picture of side effects despite sparse annotations.

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

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

Two compact sentences front-load the core action and add only high-value behavioral caveats. Every sentence contributes 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?

For a zero-parameter disconnect tool with an output schema, the description covers the action, side effect, immediacy, and recovery path. Nothing an agent needs in order to decide to call or invoke this tool is missing.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to add. The schema coverage is complete, and the zero-parameter baseline of 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: disconnect from ServiceNow, with the additional concrete outcome of removing stored credentials. This clearly distinguishes it from connect_servicenow and the servicenow_* incident tools.

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

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

The description makes the usage context clear and adds an important warning that the tool runs immediately with no preview or confirmation. It does not explicitly name alternatives or exclusions, but the resource-specific naming and the inverse connect_servicenow sibling make the appropriate use 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?

The description goes beyond the annotations by stating that the operation runs immediately, has no preview or confirmation step, and that reconnecting requires a new API token. This is important behavioral context for a state-changing tool and does not contradict the annotations.

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

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

Two sentences deliver the action, the side effect, the execution timing, and the recovery path without redundancy. It is front-loaded and every clause earns its place.

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

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

For a zero-parameter tool with an output schema, the description fully covers the invocation decision: what it does, that it runs without confirmation, and how to reconnect. No prerequisites or additional side effects are missing.

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

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

The input schema has zero parameters and 100% schema coverage, so there is nothing for the description to document. The baseline of 4 applies because no parameters exist.

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

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

The description opens with a specific action verb ('Disconnect') and names the resource (Todoist), then clarifies the concrete effect: removing the stored API token. This makes it immediately distinguishable from sibling tools like connect_todoist and the other disconnect_* tools.

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

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

The usage scenario is clearly implied by the tool name and first clause, and the description adds useful timing/recovery context. However, it never explicitly contrasts this tool with connect_todoist or states when not to use it, leaving the agent to infer the boundary.

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 context well beyond the annotations: services are user preferences, turning one on is safe and reversible, and the OS permission dialog for Calendar/Reminders/Contacts may appear on a different machine over Cloud Relay. This is valuable behavioral and environmental information not present in annotations, and nothing contradicts them.

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 earns its place: usage trigger, safety reassurance, and the OS permission nuance. Efficiently packed 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?

For a single-parameter tool with no output schemaaiman and no complex return values, the description fully covers what it does, when to use it, the safety profile, and a significant environmental edge case. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and the parameter description already lists valid service ids. The description does not add meaning beyond the schema; the mention of specific services is behavioral context rather than parameter semantics. 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 ('Turns... back ON') and resource ('a service in LMCP') and gives the precondition ('after the user turned it off'). The tool's role is unmistakable, and there is no sibling with a similar name to confuse it with.

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

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

Gives an explicit trigger: 'Use it when a tool reports that its service is turned off.' It also clarifies that these are user preferences, not failures, which prevents misuse. It doesn't mention alternatives, but none appear to exist among the sibling tools, so the guidance is adequate.

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

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

The description goes well beyond the annotations by disclosing important type-coercion behavior: JSON numbers stay numeric for SUM()/charts, JSON strings stay text even when numeric-looking, and long integer identifiers like CUIT/CBU/phone numbers are preserved as text. This is exactly the kind of behavioral nuance an agent needs to avoid data corruption. No contradiction with the annotations exists.

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

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

Two sentences with no filler. The first sentence front-loads the core purpose and file type; the second delivers high-value behavioral detail about numeric handling. Every clause earns its place and the text is easy to scan.

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

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

For a create operation, the description covers purpose, file format, optional rows, and key type behavior. The schema already documents the confirm flag and row-array shape, so those gaps are covered. One minor omission is whether an existing file at the given path is overwritten or causes an error, which could matter for an agent deciding how to proceed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining how row values will be interpreted (numbers vs. strings vs. long identifiers), which directly informs how the agent should construct the 'rows' parameter. This compensates for the schema's terse 'cell values' description.

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

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

States a specific verb and resource: 'Creates a new Excel spreadsheet (.xlsx file) with headers and optional data rows.' This clearly distinguishes it from sibling tools like excel_read and excel_write_cell, which operate on existing files/cells rather than creating a new workbook.

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

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

The purpose 'creates a new Excel spreadsheet' implies when to use this tool (new .xlsx file creation), but the description provides no explicit when-not-to-use guidance or alternatives. It does not mention that modifications to an existing spreadsheet should use excel_write_cell or that generic file creation might use file_write. The usage context is implied rather than stated.

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

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

Annotations already establish read-only/non-destructive behavior; the description adds valuable detail about the returned shape and the row-0 alignment with excel_create. It does not cover edge behaviors like cloud download fallback, but those are already fully documented in the parameter 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?

Two sentences, zero filler, with the core operation and output contract front-loaded and the round-trip rationale earning its place. Every sentence adds decision-relevant information.

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

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

With an output schema present and exhaustive parameter descriptions, the description supplies the one missing piece: the semantic relationship between this tool's output and excel_create's input. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100% and every parameter already has a detailed explanation, including sheet matching and force-download semantics. The description's headers/rows note adds general context but does not need to contribute parameter-level meaning, so the baseline 3 is appropriate.

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

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

States a specific verb (`Reads`) and resource (`Excel spreadsheet .xlsx`), then defines the return contract (`headers` first row, `rows` remaining). It is clearly distinguishable from siblings such as excel_create, excel_write_cell, and generic file_read.

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

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

Clear context: this is the tool for reading .xlsx files, and it explicitly calls out the read→create round-trip with excel_create. It does not spell out when-not-to-use vs generic file readers, so it misses explicit exclusions, but the intended use case is unmistakable.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate safety. It does add genuine behavioral context beyond that: numeric strings are only coerced when they round-trip exactly, formulas are deferred until the file opens, and a long enumerated set of out-of-file/code-executing formulas is refused with nothing written. It notably omits the `confirm: true` gate and doesn't say existing cell contents are overwritten.

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 value rules, then rejection rules, then addressing -- a sensible order. The middle sentence is very dense (the long list of refused functions) but every clause carries operative information an agent needs to avoid a rejected write.

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?

An output schema exists, so return values needn't be described, and the addressing, coercion, formula and refusal semantics are all covered. The gap is the `confirm: true` precondition for a destructive write and the fact that the target cell's prior contents are replaced, neither of which appears in the description.

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 earns a bump by adding semantics the schema cannot express -- `=` prefix meaning formula, apostrophe prefix forcing text, and the interaction between `cell` and `row`+`column` as alternatives. It adds nothing for `path`, `sheet_name`, or `confirm`, but those are adequately documented in 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 ('Writes a value to a specific cell in an Excel file') and the description immediately scopes the operation further with value-coercion and formula rules. An agent can distinguish this write tool from the sibling excel_read and excel_create 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?

The description explains how to use the tool well (A1 vs row+column addressing, `=` for formulas, apostrophe to force text), but never states when to choose this over excel_create, excel_read, or file_write, and gives no exclusions. Usage is implied by the write-a-cell framing rather than stated as guidance.

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

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

Annotations already declare read-only and non-destructive behavior, and the description adds useful behavioral context: default path, inclusion of hidden files option, and deterministic sort order. It doesn't cover edge cases like permission errors, but given annotation coverage, this is adequate.

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 concise sentences front-load the core purpose, then add return fields, default behavior, and sorting. Every word earns its place with no redundancy or fluff.

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

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

For a simple list tool with two optional parameters and an output schema, the description is fully complete. It covers default path, return fields, and ordering, leaving no important gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and their defaults. The description repeats the default behavior but adds no new parameter meaning beyond what's in the schema, matching the baseline for high schema coverage.

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

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

The description clearly states the verb 'Lists' and the resource 'files and folders in a local directory', with explicit scope (local) that distinguishes it from cloud-based list tools. It also enumerates the return fields and sort order, making the purpose unambiguous.

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

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

The description clearly identifies the tool as listing local directory contents and defaults to the home directory, providing enough context for an agent to choose this tool for local filesystem listing. However, it does not explicitly name alternatives or state when not to use it, so it misses the top score.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context beyond that: it spells out the filesystem scope ('home, external disks, cloud drives, /tmp'), the one class of locations never read (keychains, ~/.ssh, ~/.aws, browser logins, another user's home, Time Machine backups), supported file types, and encoding fallback behavior (UTF-8 with Latin-1/Windows-1252). No contradiction with annotations.

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

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

The description is appropriately sized for the tool's complexity and is front-loaded with the primary purpose. It is structured in three clear segments: (1) when to use it, (2) scope/exceptions and supported types/encoding, (3) explicit alternative tools. Every sentence earns its place; there is no filler, and the disambiguation is extremely valuable.

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

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

Given the read-only annotations (safety covered), a 100%-described schema, and an existing output schema, the description covers everything an agent needs: purpose, scope, exclusions, supported formats, encoding, and explicit routing to sibling tools. No missing operational details such as return values (output schema exists) or credentials (readOnlyHint implies no auth side effects).

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% because every parameter has a description in the input schema waters (path, offset, max_bytes, force_download). The description reinforces that 'path' is an absolute path and that the file should be plain text, but it does not add meaning for offset/max_bytes/force_download beyond what the schema already explains. Per the calibration rule, a baseline of 3 applies when schema coverage is high.

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

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

The description opens with a specific verb+resource: 'Reads a plain text file from the local filesystem by its absolute path.' It also distinguishes itself from other readers by name (onedrive_read_file, gdrive_read_file, pdf_read, word_read, excel_read) and by the 'use this unless...' clause, so an agent can immediately tell it apart from siblings.

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

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

The description explicitly states when to use this tool ('default tool for reading a local text file') and when not to: 'unless the file is a PDF, Word, Excel, or PowerPoint document, which have their own readers.' It names exact alternatives for OneDrive, Google Drive, PDF, Word, and Excel, and even lists exclusions (credential locations) that should not be read.

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 and destructiveHint false, so the safety profile is known. The description adds valuable behavioral details: case-insensitive partial matching, root default, and returned fields (path, type, size), which go beyond the structured annotations.

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

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

Two clear sentences front-load the main action and key parameters. No unnecessary words; every clause adds valuable information.

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

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

Given the full schema coverage and the presence of an output schema, the description is complete: it states the search behavior, defaults, and return types. The max_results and file_type filters are documented in the schema, so they need not be repeated here.

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 parameters are fully documented. The description repeats some schema info (case-insensitive, partial, home default) but does not add significant extra meaning 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?

Description uses a specific verb ('Searches') with a concrete resource ('files and folders by name') and scope ('starting from a root directory'), while defining case-insensitive partial matching and output fields. This clearly distinguishes it from sibling tools like file_list or cloud-specific search tools.

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

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

The description provides clear context on how to use the tool (search by name, root directory defaults to home) and what results are returned. It does not explicitly name alternative tools or exclusions, but the local-file-context is strongly 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true): it discloses the confirm=true preview-then-write workflow, that append never needs confirm, that missing parent folders are auto-created, and the hard no-write zones (shell startup files, LaunchAgents, git hooks, AI-client configs, credential locations). This is exactly the mutation-side context annotations cannot carry.

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

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

Front-loads purpose, then formats, alternatives, security boundaries, and write semantics in a tight sequence of short clauses. Despite covering a lot, no sentence is redundant and every clause carries actionable information.

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

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

For a destructive write tool with four params and an output schema, the description covers safety boundaries, the confirm/append decision, and path-creation behavior. Since an output schema exists, return values need no explanation, and 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, but the description adds real meaning: it explains that confirm triggers a preview on first call and is unnecessary for new files or appends, and that append adds to the end. This clarifies the interaction between the two boolean flags beyond their individual schema descriptions.

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

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

States a specific verb and resource ('Writes text to a local file') and immediately enumerates the three modes (create, overwrite, append). It also names the sibling tools it is not (word_create, excel_create, ppt_create), so an agent can distinguish it from adjacent document tools without inspection.

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: the supported file types (.txt/.md/.csv/.json/.log and plain-text/code) and explicit routing to word_create/excel_create/ppt_create for office formats. It does not, however, address when to prefer local file_write over cloud siblings like gdrive_write_file or onedrive_write_file, so the when-not guidance is incomplete.

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 provide readOnlyHint=true and destructiveHint=false; the description adds valuable context beyond that: it refuses credential and identity locations and states it is Spotlight-free. This goes beyond what annotations alone declare.

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, front-loaded with the core action, and no filler. Each sentence earns its place: core function, scope, and security exclusions all appear in compact form.

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

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

The output schema plus annotations carry return values and safety, and the description covers base function, scope, and sensitive-path behavior. It is complete for a simple list tool; finer details like hidden files or error behaviors are not critical for correct invocation.

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

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

Schema coverage is 100% and both parameters (path and limit) already have descriptions. The tool description does not add parameter-level meaning beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description uses a specific verb ('Lists') and resource ('files and folders in a directory') and sharpens scope with 'any folder on this Mac' and 'Spotlight-free'. It clearly differentiates from search-like siblings, but it does not explicitly distinguish itself from the adjacent file_list sibling.

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

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

No explicit guidance on when to prefer this tool over alternatives such as file_list or finder_search. The sensitive-path refusal gives clear negative boundaries, and 'Spotlight-free' implies a non-indexed file list, but the description leaves the when/when-not comparison mostly implicit.

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

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

Annotations already cover read-only and non-destructive behavior; the description adds the Spotlight/mdfind implementation note and, more importantly, the refusal to search credential/identity locations. This is useful behavioral context beyond the structured annotations.

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

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

Two compact sentences lead with the core action and scope, then add the scoping flag and the security caveat. Every sentence earns its place.

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

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

With annotations, full schema coverage, and an output schema, the description is almost complete; the only notable omission is a caveat that Spotlight indexing may affect freshness or hidden-file coverage. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents query, path, and limit. The description's path= mention adds a usage hint but is redundant; it also says 'by name' while the schema says 'filename or content,' adding slight ambiguity.

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

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

States a specific verb ('searches'), a concrete resource ('files by name anywhere on this Mac'), and a distinctive mechanism (mdfind/Spotlight), making it easy to tell apart from cloud-storage and note/message search siblings.

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

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

The description gives a clear local-search context and instructs how to scope with path=, but it never names an alternative (e.g., file_search or finder_list) or says when not to use this tool. Usage is implied rather than explicit.

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

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

Annotations already mark this destructive, but the description adds substantial context: cloud sync to Drive trash, pointer files removing real documents, refusal to delete non-empty folders, and the two-step preview/confirm flow. This goes well beyond the annotations and 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?

Three sentences, each carrying essential information: the core action, notable edge cases, and the confirmation workflow. No filler or redundant restatement of the tool name.

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

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

The description covers the destructive nature, cloud sync implications, folder-content limitation, pointer behavior, and the required confirm step. With an output schema present, this is complete enough for an agent to invoke the tool correctly and safely.

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

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

Schema coverage is 100% and both parameters already have clear descriptions. The description adds meaningful operational detail by explaining that the first call is a preview and confirm=true is the actual deletion trigger, reinforcing the schema's 'Must be true' note.

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

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

The description opens with a specific verb and resource: 'Deletes a file or an empty folder from the synced Google Drive folder.' It also clarifies non-obvious behavior (pointer files deleting the real Google Doc) and distinguishes this from generic file deletion by scoping it to the Google Drive mount.

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

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

The description clearly states when deletion is allowed (file or empty folder) and when it is not (folders with contents). It does not explicitly name an alternative tool, but the Google Drive scope and the preview/confirm workflow make appropriate usage evident.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the 'synced' context and a performance note, but does not detail return format or edge cases; output schema covers the return shape. This is minimal extra context, hence a 3.

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

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

The description is one succinct sentence that front-loads the purpose and includes a useful cost comparison. No redundant words or 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 simple tool with one parameter, an output schema, and clear annotations, the description is complete. It states what is returned, the target resource, and a key differentiator, which is enough for correct selection and invocation.

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

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

Schema coverage is 100%: the single required 'path' parameter has a clear description. The description adds only a minor contextual note about the synced Google Drive, not materially expanding on the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as returning metadata (size, dates, type) for a file/folder in the synced Google Drive, and it distinguishes itself from sibling tools by noting it is cheaper than listing the whole directory. This gives a specific resource and a differentiator.

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

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

It implies when to use this tool: when you need metadata for a specific file/folder and want a cheaper alternative to listing a directory. However, it doesn't explicitly name sibling alternatives or provide exclusionary guidance, so it stops short of a 5.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds valuable context: it specifies the paths refer to the 'locally-synced folder' and that results are truncated to `limit` entries with a default of 1000. This gives the agent a more accurate behavioral model.

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 three sentences long: the first states the core action, the second provides a prerequisite, and the third details the limit bound. Every sentence earns its place, and the text is front-loaded, making it easy for an agent to parse quickly.

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 list tool with an output schema and read-only annotations, the description covers all essential aspects: what it lists, where (locally-synced folder), how to get valid paths, and the result limit. It is sufficiently complete without needing to explain return values since an output schema exists.

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 input schema fully describes both parameters (`path` and `limit`) with their types and limits. The description's mention of 'limit entries (default 1000)' simply restates schema information, adding no new semantic meaning. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action ('Lists files and folders') and resource ('in a Google Drive path'). This distinguishes it from sibling tools like gdrive_search_files and gdrive_file_info, which serve different purposes.

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

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

The description provides a clear prerequisite ('Use gdrive_root first for valid roots') and clarifies path structure ('My Drive' and 'Shared drives' are inside each mount). It does not explicitly mention alternatives, but the usage context is clear enough for an agent to decide when to invoke it.

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

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

Beyond the readOnlyHint annotation, the description adds useful behavioral context: it auto-detects UTF-8 with Latin-1/CP1252 fallback, and warns about .gdoc/.gsheet pointer files. It does not contradict any annotation and enhances the agent's understanding of edge cases.

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, front-loaded with the main action, then important caveats, and closes with an alternative. Every sentence adds value with no 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?

Given the presence of an output schema, complete parameter documentation, and read-only annotations, the description covers all essential aspects: file types, encoding behavior, Google Drive specifics, and when to use a different tool. The tool is simple, and the description leaves no major questions.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description's mention of auto-detected encoding aligns with the encoding parameter but adds no new syntax beyond the schema. This matches the baseline 3.

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

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

The description clearly states the tool 'Reads a text file from the synced Google Drive folder' with a specific verb, resource, and scope. It distinguishes itself from the sibling file_read by explicitly noting 'For files outside Google Drive, use file_read'.

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

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

Provides explicit when-to-use (text files in the synced Google Drive folder) and when-not-to-use (native Google Docs/Sheets/Slides, which sync as .gdoc/.gsheet pointers). It also names an alternative (file_read) for files outside Google Drive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds meaningful behavioral context by explaining it reads the locally synced folder and requires no Google API or OAuth. This clarifies mechanism and side-effect-free nature beyond the annotation flags.

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

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

Three short sentences front-load the core purpose, then add usage guidance and technical context. Every sentence contributes new information with no redundancy or padding.

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

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

This is a simple zero-parameter listing tool with an output schema and safe-read annotations. The description covers what is listed, the entry-point role, and the local/no-auth mechanism, which fully satisfies the context needed for an agent to select and invoke 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?

The tool takes zero parameters, so the schema (100% coverage) fully defines the input contract. The description appropriately adds no parameter details; the baseline of 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?

The description opens with a specific action ('Lists') and a precise resource ('Google Drive folders synced on this Mac'), enumerating My Drive, Shared drives, and per-account mounts. It clearly distinguishes this tool from sibling gdrive_* tools by positioning it as the root/entry point for valid paths.

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

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

It gives explicit context: 'Start here to get valid paths for the other gdrive_* tools,' and notes it reads the folder already synced by Google Drive for Desktop. It doesn't explicitly state when not to use it or name alternatives, but the intended sequencing is clear.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral details beyond the annotations: it is recursive, returns at most max_results (default 50), and searches by name. This provides meaningful context about the tool's behavior without contradicting the annotations.

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

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

The description is a single, front-loaded sentence that immediately states the tool's purpose and key constraints. Every phrase earns its place: 'synced Google Drive folder,' 'by name (recursive),' and 'max_results matches (default 50).' There is zero wasted wording.

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

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

Given that an output schema exists and annotations are present, the description does not need to explain return values or safety. It covers the essential action, scope, recursion, and result limiting. The only minor gap is that it does not clarify what 'the synced Google Drive folder' refers to (e.g., whether it searches all mounted Google Drives by default), but the root parameter and schema help fill that in.

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

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

Schema description coverage is 100%, meaning all three parameters are already documented. The description adds no new parameter-level details beyond what the schema provides—it only reiterates the 'by name' and 'max_results' concepts. Since the schema carries the full load, a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Searches'), a specific resource ('the synced Google Drive folder'), and the scope ('by name (recursive)'). This clearly distinguishes it from sibling tools like gdrive_list_files or gdrive_read_file. The purpose is unambiguous and immediately understandable.

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

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

The description implies its usage context: searching for files by name in Google Drive. However, it does not explicitly mention alternatives or exclusions, such as 'use this instead of gdrive_list_files when you need to find a file by name.' The guidance is implied rather than explicit, so it earns a mid-range score.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the danger is known. The description adds a genuinely useful behavioral detail beyond them: the two-phase confirm flow where the first call returns a preview instead of writing. It stops short of covering auth/permission needs or failure behavior.

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