Raziel

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the exact files to read (AGENTS, CLAUDE, replit), which goes beyond the annotation's safety profile.

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, front-loaded sentence that conveys the essential information without any unnecessary words.

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

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

With only one parameter and no output schema, the description adequately covers the tool's purpose and parameter. It does not describe the return format, but given readOnlyHint, the agent can infer file content output; minor completeness gap.

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

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

Schema coverage is 100%, and the parameter's description already lists the available files. The tool description merely repeats this list, adding no new 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?

The description clearly states the verb 'Read' and the resource 'adapter instruction file', then lists specific file names (AGENTS, CLAUDE, replit), which distinguishes it from sibling tools that deal with other aspects of tide.

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 guidance on when to use this tool vs alternatives; it simply states what it does without context on prerequisites or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely non-redundant behavior — that Phase 1 is vendor-neutral and names no vendor, that Phase 2 is opt-in, and that the deliverable is a director-facing PDF. It omits auth/permission requirements and any indication of runtime or cost, which keeps it short of a 5.

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

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

The content is front-loaded: the assessment and its scoring model lead, phasing follows, and the use-case triggers close. The opening sentence is heavily packed with parentheticals, but each clause carries distinct information and nothing is filler.

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

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

With no output schema, the description does the work of explaining the return — a scored, three-core, director-facing PDF with a phased companion. That is enough for an agent to set expectations, though it never says how the result is returned or how the 'part' paging interacts with the response.

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

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

The single 'part' parameter is fully documented in the schema (100% coverage), so the schema carries the load. The description hints at multi-part delivery via the 'delivered as a director-facing PDF' framing but never mentions the parameter or its default behavior, so it adds no meaning beyond the structured field — 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 states a specific verb and artifact — run a Blast Radius Assessment on an EXISTING app, producing an adversarial vendor-neutral map scored across three named cores and delivered as a director-facing PDF. That level of specificity distinguishes it from adjacent siblings like tide_security_analysis, tide_gaps, and tide_doctor without the agent needing to open any other schema.

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

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

It gives concrete invocation triggers ('assess', 'red team', 'threat model', 'find the security gaps in', making a before/after security case) and scopes the input to an existing application. It does not, however, name alternatives or state when a sibling such as tide_security_analysis or tide_gaps would be the better choice, so routing among similar tools 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?

Annotation contradiction: readOnlyHint=true but the description explicitly states it 'uploads both' files and 'saves+signs the IdP settings', and mentions 'set-branding = save AND re-sign'. This is a write/mutation operation, directly contradicting the read-only 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 front-loaded with the core purpose and each sentence adds functional detail (returns a command, validation, upload contract, prompts). It is slightly verbose but not wasteful; the length is justified by the tool's 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 is highly complete for a complex tool: it explains the generated outputs (ready-to-run command, verified upload contract, image-model prompts), validation criteria, upload specs, and security exclusions. No output schema exists, so the description fully carries the burden of explaining return values and constraints.

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% with descriptions for all four parameters. The description adds context by saying 'Pass realm/accent/appName to get the command pre-filled' and details upload constraints like 'SVG REJECTED' and '5 MB cap', enriching the parameter semantics 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 leads with a clear, specific verb+resource: 'BRAND THE ENCLAVE FOR THE USER — generate a logo + background and upload them'. It explicitly covers branding, logo, background, theming, and skinning, and the 'CALL THIS whenever...' line distinguishes it from siblings by scoping its use 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?

The description gives an explicit trigger: 'CALL THIS whenever branding, a logo, a background, theming or \'skinning\' the enclave or login screen comes up'. It also instructs to 'RUN the command; do not just describe it'. However, it does not mention when not to use it or name alternative tools.

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 by structured data. The description adds nothing beyond the schema — no mention of the multi-part delivery mechanics, size limits, or anything an agent couldn't already infer from the parameter docs.

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 front-loaded sentence with no wasted framing. The parenthetical file list is somewhat redundant with the schema but is compact and harmless.

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

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

For a read-only retrieval tool with a fully documented schema and annotations covering the safety profile, the description is sufficient. The absence of output-schema commentary is fine since none exists, and the schema explains part/section slicing.

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 'part' and 'section' are already documented with examples in the schema. The description's enumerated file list duplicates what the 'name' parameter description already provides, adding little new meaning. 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 clear verb ('Read') and resource ('canon file') and enumerates the kinds of documents available. It lets an agent distinguish this lookup tool from siblings like tide_list or tide_playbook, though it never explicitly names an alternative.

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

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

There is no statement of when to use this tool versus alternatives, nor any prerequisites. The list of file names hints at the domain but the agent must infer that this is the retrieval path for canon content referenced by other documents.

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, implying safe, read-only behavior. The description adds no additional behavioral details (e.g., what happens if the situation is not understood, or how the recommendation is made), so it meets the baseline without adding value.

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, clear sentence with no extraneous information. It efficiently conveys the tool's purpose.

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 lacks context about the tool's return value or behavior. With no output schema, it should explain what a playbook recommendation entails, but it only states it recommends a playbook. Important details 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?

Schema description coverage is 100% (the single 'situation' parameter is described). The tool description does not add any meaning beyond the schema's parameter description, so the 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 clearly states the tool recommends a playbook for a situation. The verb 'recommend' and resource 'playbook' are specific, and it distinguishes from sibling 'tide_choose_scenario' by focusing on playbooks. However, it does not elaborate on what constitutes a playbook, leaving some ambiguity.

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 usage guidance is provided. The description does not indicate when to use this tool instead of alternatives like 'tide_playbook' or 'tide_list', nor does it mention when not to use it or prerequisites.

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

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

Annotations already indicate readOnlyHint=true, covering safety. The description adds that it performs matching, which is consistent. It provides limited additional behavioral detail beyond the schema and 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?

A single sentence of 16 words, directly stating the tool's purpose with no redundancy. Highly concise 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?

The description does not specify what the tool returns (e.g., scenario name or identifier), leaving an agent without output expectations. Given no output schema and a single input parameter, it is minimally adequate but could be improved by clarifying the return value.

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% with a clear description and example for the 'situation' parameter. The tool description adds no further parameter semantics, so baseline score of 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 clearly states the tool matches a user request to a known scenario pattern, providing a specific verb and resource. It hints at a pipeline role ('before falling back') but does not explicitly distinguish from closely related siblings like 'tide_choose_playbook' or 'tide_list_scenarios'.

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?

Implies usage when you have a user request and need to find a scenario, with fallback to generic playbooks. However, it lacks explicit when-to-use/when-not-to-use guidance and does not mention alternatives among siblings.

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

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

Adds substantial context beyond the annotations: which faults it self-repairs (re-copies DPoP page byte-exact, corrects rewrite path, gitignores .env), which it only prints for the agent to apply, and the checkOnly CI mode. It also clarifies the call returns only a command, which reconciles the 'REPAIRS' language with readOnlyHint=true. The mild tension between 'repairs' and readOnly/destructive annotations is explained rather than contradicted, so no penalty beyond being slightly dense.

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

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

Front-loaded with the core purpose and the imperative usage rule, then the coverage list. It is long and dense (long all-caps coverage sentence), but each listed fault earns its place by defining scope; only marginal trimming is possible.

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

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

With no output schema, the description carries the return-value burden and does so: it states the call returns only a command and that the agent applies the remaining fixes. Combined with coverage of what it checks and fixes, an agent has enough to invoke and act correctly, though the exact output shape is only loosely described.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including their defaults. The description reinforces the realm/appUrl scoping and checkOnly behavior but adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource+scope: find and fix what is wrong with a Tide app in one command. It enumerates the concrete fault classes it covers (DPoP page, useDPoP JSX prop, createTideCloakProxy without protectedRoutes, etc.), so an agent can distinguish it from siblings like tide_dpop_asset or tide_security_analysis 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?

Explicit when-to-use: 'CALL THIS after scaffolding or changing auth code, BEFORE telling the user it works, and FIRST whenever a login or an API check misbehaves.' It also states the workflow constraint that the agent must apply the printed fixes and not forward the list to the user, which is genuine routing 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 establish readOnlyHint=true and destructiveHint=false, and the description is consistent with them. Beyond that it discloses real behavioral context: the SDK version that ships the file (0.14.34), that older SDKs and the TideCloak container do not, and that a stale GitHub copy posts to window.parent and breaks the popup fallback.

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 what the tool returns, followed by the version caveat and the call triggers. Every clause carries information (version, failure codes, stale-copy pitfall), though the density of error strings and file paths makes it slightly heavy for a single call.

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

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

With no output schema, the description carries the return burden and does so fully: install command, sha256, rewrite/CSP wiring, and verification. It also supplies the failure modes that justify invocation, leaving nothing an agent needs in order 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?

The tool takes zero parameters, so the schema baseline is 4 and there is nothing for the description to disambiguate. No parameter-level detail is needed or missing.

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

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

States a specific verb and resource: it returns the exact install command for public/tide_dpop_auth.html, the DPoP relay page, plus its sha256, next.config.ts wiring, and verification steps. This is unmistakably distinct from siblings like tide_doctor or tide_scaffold, which an agent can rule out without opening a schema.

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

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

Gives explicit triggers: call whenever DPoP is enabled (noting it is on by default), on login failure with TIDE-SWE-UNHANDLED or 'Popup DPoP verification failed to load', and before copying the file from anywhere else. It also names the alternative source to avoid (the stale GitHub copy), so when-not-to-source-elsewhere is covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered elsewhere. The description adds no behavioral context beyond that — no mention of pagination, return format, or whether the register is a fixed snapshot versus live 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?

A single tight sentence fragment with the core action ('Read the gap register') front-loaded and the clarifying gloss immediately after. 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?

For a simple, read-only, single-optional-parameter tool with full schema coverage and no output schema, the description covers the essentials. The main gap is that 'the pack' and the register's structure are left as unexplained jargon an agent must guess at.

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 single 'part' parameter is fully documented in the schema, including the omit-for-part-1 default and the multi-part behavior. The description adds nothing about the parameter, 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 (Read) and resource (the gap register), then glosses the resource as 'what is still uncertain or unresolved in the pack.' Clear enough to know what it returns, but it offers no differentiation from siblings like tide_doctor or tide_list, and 'the pack' is undefined domain jargon.

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

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

There is no statement of when to reach for this tool versus alternatives such as tide_list or tide_doctor, nor any prerequisites or context. Usage is only inferable from the resource name, not from explicit guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the content returned and the downstream irreversibility constraint (a realm cannot be moved after choosing), which is the behavioral stake that matters for sequencing.

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

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

Front-loaded with the core decision and efficiently structured around purpose, rationale, and triggers. Slightly long trigger enumeration, but each line earns its place by widening match surface for a high-stakes pre-deployment call.

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

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

No output schema exists, so the description carries the return burden — and it does, naming trade-offs, trust model, API reference, and playbook. For a read-only single-param document tool, nothing needed 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?

Only one parameter ('part') exists and its schema description coverage is 100%, so the schema fully documents it. The description adds no meaning beyond that, 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 the exact decision the tool serves — local Docker vs partner-hosted TideCloak — and enumerates the payload (trade-offs, trust model, Skycloak API reference, provisioning playbook). An agent can distinguish this from generic siblings like tide_playbook or tide_choose_scenario 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 imperative ('CALL THIS BEFORE STARTING ANY TIDECLOAK DEPLOYMENT'), the reason ('the choice must be made up front (I-17) because a realm cannot be moved between local and hosted afterwards'), a trigger list, and the condition that selects it ('where local-vs-hosted has not been settled'). Routing is unambiguous.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, covering safety. The description adds context about the data source ('Tide agent pack') but does not elaborate on behavior beyond the schema. It is consistent 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 a single, efficient sentence with no extraneous information. It is front-loaded and directly states purpose.

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 one enum parameter, no output schema, and clear annotations, the description is fully adequate. It defines scope ('in the Tide agent pack') and filtering ('by category'), leaving no gaps.

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 description mentions 'by category', aligning with the parameter. However, it does not add additional meaning beyond the schema-provided enum or explain the parameter's role further.

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 'List all available content in the Tide agent pack by category', specifying a specific verb ('list') and resource ('Tide agent pack'), with a filtering dimension ('category'). It distinguishes from siblings like tide_canon or tide_skill, which are individual item 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 no guidance on when to use this tool versus alternatives like tide_list_scenarios or other listing tools. It does not mention prerequisites, exclusions, or typical contexts.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds the location constraint ('under reference-apps/'), providing useful behavioral context beyond annotations. However, no additional details (e.g., behavior if no patterns exist) are given.

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

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

The description is a single, front-loaded sentence. Every word is necessary and clearly communicates the tool's action and scope. No wasted text.

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 adequately covers the tool's purpose and scope given zero parameters and no output schema. However, it could be more complete by hinting at the output format or any prerequisites (e.g., existence of the directory). Still, for a simple listing tool, it is sufficiently 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?

There are no parameters, so no parameter semantics are needed. The schema coverage is trivially 100%. The baseline score for zero parameters is 4, and the description does not need to add anything further.

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: listing scenario patterns specifically under the 'reference-apps/' directory. The verb 'List' and resource 'scenario patterns' are specific. Among siblings like tide_list (general listing) and tide_scenario (single scenario), this tool's focus on patterns under a specific path distinguishes it effectively.

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 guidelines are provided on when to use this tool versus alternatives. With 14 sibling tools, explicit usage context or exclusions would be very helpful but are entirely absent.

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, so the description aligns by calling it a 'read-only DIAGNOSTIC'. It adds context about the four mechanisms and the returned artifacts (script, modal). It doesn't explicitly state it won't modify anything, but the read-only attribute covers that. 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 a single block but clearly explains the purpose, return content, and usage triggers. It's detailed but not overly verbose. Could be structured with bullets, but it's effective.

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 explains the diagnostic nature, the four mechanisms, and the proactive call scenario. However, it doesn't specify output format or error handling, but given the read-only annotation, it's adequate.

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?

All 6 parameters have descriptions in the schema, covering fields, appName, framework, etc. The description mentions 'fields' implicitly but doesn't elaborate beyond schema. Since schema coverage is 100%, a score of 4 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 specific purpose: stopping Keycloak's 'Update Account Information' page and providing a diagnostic plus a modal to collect details in-app. It names the exact resource and what the tool returns, distinguishing it from sibling tools (which are all different tide_* services).

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 'CALL THIS whenever signup, onboarding, 'Update Account Information', a profile/details form, or 'what users see after they create an account' comes up' and even suggests proactive use after bootstrapping. This is clear usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that—nothing about multi-part pagination semantics or return shape (and no output schema exists to compensate).

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 short, front-loaded sentence with no waste. It is appropriately sized for a simple read tool, though it borders on too terse to add much beyond the title.

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

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

For a low-complexity read tool with 100% schema coverage and no output schema, the definition is minimally adequate. It still omits routing context relative to tide_choose_playbook and does not note the multi-part nature of delivery outside the schema.

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

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

Schema coverage is 100%, so the schema fully documents both 'name' (with the enumerated list of playbooks) and 'part' (pagination). The description adds no meaning beyond the schema, 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 and resource: 'Read a step-by-step playbook.' An agent knows exactly what the tool returns. However, it does not distinguish itself from sibling tide_choose_playbook, which also concerns playbook selection.

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

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

No when-to-use or when-not-to-use guidance. It neither names alternatives (e.g., tide_choose_playbook for picking a task) nor states prerequisites such as needing a valid playbook name first. Usage is only weakly implied by the verb.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of 'Read' aligns. It adds no further behavioral context (e.g., authentication, output format), but does not contradict 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?

Extremely concise: one sentence with no wasted words. Front-loaded with the primary purpose.

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?

Adequate for a simple read tool with one parameter, but lacks explanation of the return value or any side effects. With no output schema, more context would help.

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 description does not add meaning beyond the listed options in the parameter's 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 states the action ('Read') and the resource ('reusable starter prompt'), distinguishing it from sibling tools like tide_list (listing) or tide_playbook (different resource). However, it could be more specific about the 'pack' context.

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 guidance on when to use this tool versus alternatives. Sibling tools exist (e.g., tide_list for listing prompts) but the description doesn't provide context for selection.

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, and the description is consistent with that, explaining the tool returns commands rather than mutating state. It adds useful behavioral context about what the scaffold produces and why copying beats retyping, though it says nothing about prerequisites, side effects if any, or how the returned commands are meant to be run.

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

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

Front-loaded with the core purpose, then the when-to-use rule, then the exclusion. Dense but every clause carries information. The all-caps emphasis is slightly heavy but does not obscure the message.

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

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

There is no output schema, so the description usefully characterizes the return value as exact copy/install/bootstrap/check commands. Combined with the explicit usage conditions, an agent has what it needs to select and invoke the tool correctly, though return-format specifics (how commands are presented) remain unstated.

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 appDir, appName, template, and situation are already fully documented in the schema, including the enum values. The description adds only the selection hint ('Pass situation and it picks the template; or name one'), which the schema largely covers. 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 ('Start a new Tide app from a working template') and immediately clarifies the output ('Returns the exact commands to copy a complete, building app'). It enumerates what the app contains (login, DPoP page and wiring, token/proof verification, realm bootstrap) and explicitly contrasts itself with adding Tide to an existing app, so an agent can distinguish it from siblings like tide_onboarding.

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

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

Gives explicit timing ('CALL THIS when building a new app, BEFORE writing any auth code') plus the rationale for doing so. It states a clear exclusion ('Not for adding Tide to an existing app') and explains the two selection paths (`situation` vs naming a template). This is close to ideal when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that the source is a markdown file at a known repo path, but it says nothing about the multi-part response behavior or what the summary contains, which is a missed opportunity given the lower bar set by 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?

A single, front-loaded sentence with zero filler. It is efficient, though extremely terse for a tool with a nuanced multi-part return behavior.

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

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

No output schema exists, so the description does not need to enumerate return values, but it also never characterizes what a 'scenario summary' is or how it relates to the sibling scenario tools. For a simple read tool this is adequate but leaves the agent guessing about the content and its relationship to alternatives.

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 'name' (with its full enumeration of valid scenarios) and 'part' are already fully documented in the schema. The description's path pattern loosely reinforces the 'name' param but adds no syntax or format meaning beyond what the schema provides; 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 ('Read') and resource ('scenario summary') and even names the backing file path (reference-apps/<scenario>/scenario.md). It is clear what the tool returns, but it does not distinguish itself from siblings like tide_scenario_manifest, tide_scenario_roles, or tide_list_scenarios, which an agent must disambiguate on its own.

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

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

There is no explicit when-to-use guidance and no comparison against the many sibling scenario tools (tide_list_scenarios, tide_choose_scenario, tide_scenario_manifest). The only routing hint is implicit in the schema's 'part' parameter, which is not usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the source path, implying it returns the contents of a markdown file, but says nothing about format, auth, or behavior on a missing scenario. A 3 reflects modest added value beyond 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?

A single, front-loaded sentence with the verb first and no wasted words. Appropriately sized for a simple read tool, though the path placeholder is slightly redundant with the schema.

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

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

For a simple read-only tool the core is present, and the source path hints at the return content. However, with no output schema and no statement of what a missing scenario yields, minor gaps remain.

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 name parameter already lists all valid scenario values. The description's <scenario> placeholder merely echoes the schema, adding no new syntax or format detail. 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 (Read) and resource (scenario bootstrap sequence), with the source path reference-apps/<scenario>/bootstrap-sequence.md clarifying what is read. It is fairly distinguishable from siblings, though it does not explicitly contrast with tide_scenario or tide_scenario_manifest which read other scenario files.

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 when-to-use guidance, prerequisites, or named alternatives are given. The agent must infer when to call this versus tide_scenario or tide_scenario_manifest.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description contributes only the source path (reference-apps/<scenario>/manifest.yaml), adding marginal context about where data comes from, but says nothing about error behavior for an unknown scenario.

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

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

A single tight sentence with the resource and the path front-loaded; every word earns its place and there is no filler.

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

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

For a simple one-parameter read tool with full schema coverage and an annotation-declared safety profile, the essentials are present. It stops short of describing what a manifest contains or how a missing/invalid scenario is handled, leaving a modest gap.

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

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

Schema coverage is 100% and the single 'name' parameter already enumerates the eight valid scenario values in its own description. The description's '<scenario>' placeholder merely echoes the schema, adding no new semantics, 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 ('Read') and resource ('scenario manifest') plus the exact file location in the repo, so the agent knows precisely what is fetched. It does not, however, differentiate itself from close siblings such as tide_scenario or tide_list_scenarios.

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

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

There is no guidance on when to call this instead of tide_scenario, tide_scenario_roles, or tide_scaffold, nor any prerequisite or ordering note. The agent must infer the use case from the name alone.

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, consistent with the 'Read' verb. The description adds the concrete file location (reference-apps/<scenario>/role-policy-matrix.md), which is useful context, but says nothing about failure behavior (e.g., missing file/scenario) or return format.

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

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

One tightly written sentence with the resource and source path front-loaded and no filler. It is short enough that nothing is wasted, though the brevity contributes to the guidance gaps noted elsewhere.

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 read tool this is close to adequate, and the description hints at the returned artifact (a role-policy matrix markdown). With no output schema, however, it should say more about what the returned content contains or how errors surface.

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 'name' parameter already enumerates the eight available scenario names, so the schema carries the parameter burden. The description only echoes the parameter as '<scenario>' in the path template, adding no syntax or validation detail beyond the schema.

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

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

States a specific verb (Read) and resource (scenario role-policy matrix) plus the exact source path, so an agent knows what is retrieved. It does not explicitly differentiate itself from sibling tools like tide_scenario_manifest or tide_scenario, though the 'role-policy matrix' resource is distinctive enough to infer.

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 statement of when to use this tool versus alternatives such as tide_scenario_manifest, nor any prerequisites (e.g., scenario must be scaffolded first). Usage must be inferred entirely from the resource name.

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 value beyond that by disclosing the return payload (Security Analyst instructions, SG-01…SG-18 gap table, runtime-probe procedures) and the schema param notes the authorization caveat for live probing. This is solid behavioral context for a read-only analysis 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?

Three sentences, front-loaded with the core action and then the returned artifacts and trigger phrases. The capitalization of 'EXISTING' usefully emphasizes scope. Slightly dense but 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?

No output schema exists, so the description appropriately summarizes return content (role instructions, gap table, probe procedures). Parameters are fully covered by the schema and safety is covered by annotations. Complete for a read-only analysis tool, with only minor room to clarify sibling routing.

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 'part' and 'include_runtime_probes', including the part-1 default and the authorization condition. The description adds little beyond what the schema provides, 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+resource (analyze an existing system for security gaps, map to Tide capabilities) and clarifies scope with 'EXISTING (possibly non-Tide)'. It also names the concrete artifacts returned. It does not explicitly distinguish itself from close siblings like tide_gaps or tide_blast_radius, so differentiation is only implicit.

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 trigger phrases ('do a security analysis', 'where is my auth weak', 'what would Tide change about my security') that make the when-to-use condition clear. However, it names no alternative tool or when-not-to-use condition, so routing among the many tide_* siblings still requires inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that - no note on pagination behavior, document size, or what a returned skill contains.

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

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

A single efficient sentence with zero waste and the core action front-loaded. It is arguably under-specified, but there is no padding to trim.

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

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

For a simple read tool with full schema coverage and annotations covering safety, the structured fields carry most of the load. The description still leaves the agent guessing about output pagination and the scope of a 'skill', and there is no output schema to compensate.

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%; the name param even enumerates the available skills and the part/section params are well documented in the schema. The description adds no parameter semantics of its own, 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 clear verb ("Read") and resource ("composable skill definition"), so the agent knows it retrieves a document. However, it offers no differentiation from siblings like tide_list or tide_scenario, which could also plausibly return skill-related content.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The schema hints at pagination and section filtering, but the description gives the agent nothing about when to reach for this tool versus its many siblings.

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