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

Goes well beyond the annotations: it discloses that the call is asynchronous ("returns once the cancel is queued"), that history records when the prompt actually stops, the authorization prerequisite, and precise 404/403 semantics tied to visibility scopes. This is exactly the behavioral detail an agent needs 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-loads the core action, then layers on async behavior, permissions, and error semantics in a logical order with no filler. It is dense but every sentence carries actionable information, so it is not padded.

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

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

With no output schema, the description carries the return-behavior burden and does so (cancel queued vs. history-recorded completion), plus permissions and visibility scoping. An agent has everything needed to call this correctly and interpret the outcome.

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 67% and the one undocumented parameter, promptAcceptedSequenceId, is explained in the description as the ID the session's history records for the prompt. session_id and the account-override header are already documented in the schema, so the description fills the remaining gap well.

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 ("Ask an agent session to stop working on a prompt") and identifies the exact identifier the operation targets. This clearly distinguishes it from siblings like send_agent_session_message or get_agent_session, though it never names an alternative 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 strong operative context: it explains the grant required to run the session's agent and the visibility rules that determine whether a session is even reachable (404 vs 403). It stops short of explicitly contrasting when to cancel versus send a new message, but the usage conditions are clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered structurally. The description adds the useful constraint that only running or queued runs are cancellable, but says nothing about reversibility, whether in-flight tasks are killed, idempotency, or the two-phase force retry documented only in 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?

A single front-loaded sentence with no filler or repetition. It is efficient, though the brevity borders on under-specification for a destructive operation rather than true tightness.

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, 3-parameter mutation with no output schema, the description omits what happens after the call (resulting run status, whether polling get_pipeline_run_status is needed), the required 'CANCELLING'-then-force sequence, and any permission context. The agent is left to reconstruct the operating procedure from the schema and sibling names alone.

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

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

Schema description coverage is 67% and the schema itself is unusually thorough, spelling out the 'force' semantics (must already be CANCELLING or a 400 results) and account-scoping rules for the header. The description contributes only 'by its ID', which merely restates the required pipeline_run_id, so it neither compensates for nor detracts from 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 (cancel), a specific resource (pipeline run), and the qualifying state scope ('running or queued') plus the lookup key (by its ID). That is enough to separate it from delete_pipeline, pause_pipeline, and cancel_agent_session_prompt, though it never names a sibling or boundary 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?

No when-to-use guidance beyond the vague state qualifier. It does not say how this differs from pause_pipeline, whether the cancellation is the intended replacement for pause, or when the two-phase force flow applies. The agent must infer all routing decisions from the sibling list.

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 give the safety profile (readOnlyHint=false, destructiveHint=false), so the description earns credit by adding real behavioral context: secrets are returned masked, gitEnabled depends on an existing workspace git connection, avatarPath must resolve against the avatar catalog, and prompts are Markdown. It does not cover duplicate-name behavior, limits, or auth requirements beyond the credential scoping.

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 scope statement is front-loaded and the parameter notes are packed into a single dense sentence with no filler. It is appropriately sized, though the second sentence reads as a comma-spliced list that could be marginally tighter.

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 described, but for a 12-parameter creation tool with near-zero schema descriptions, the description leaves most optional fields (effort, model, sample prompts, response prompt, description) undefined. An agent could call it with only a name, but cannot confidently populate the rest.

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 only 8% across 12 parameters, so the description must carry the burden but covers just four (systemPrompt, avatarPath, gitEnabled, llmKeyType) plus a note on secrets. Nothing is said about name, description, defaultEffort, samplePrompts, defaultModelId, responsePrompt, or the header parameter, all of which the schema leaves undocumented.

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

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

States a specific verb and resource ("Create an agent") and scopes it to the workspace the credential resolves to, which separates it from generic create_* siblings. It does not explicitly contrast with update_agent or create_agent_session, so it falls short of full sibling differentiation.

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

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

There is no when-to-use, when-not-to-use, or alternative guidance. The clause about gitEnabled needing the workspace's git connection is a constraint rather than a usage rule, and no sibling (update_agent, list_agents, create_agent_session) is mentioned as an alternative.

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 readOnlyHint=false and destructiveHint=false, so the description carries the interesting load and does it well: the call is asynchronous and returns once the prompt is queued, with the reply read from GET /sessions/{session_id}/history/messages. It also discloses the auth asymmetry (OAuth vs API key 400), the visibility/session-reuse behavior with incidentId, and the grant requirements for running the agent and viewing the incident.

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

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

Front-loaded with the core action, then progressively layers async behavior, auth, and scoping. Nearly every sentence carries non-redundant information, though the closing grant sentence packs two separate permission requirements into one dense clause.

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 sparse schema documentation and an output schema already covering returns, the description supplies the missing operational context: async contract, where replies are read, credential requirements per mode, session-reuse semantics, and required grants. The only real gap is the tuning parameters (effort, modelId, pipelineEditorContext), which is minor against the overall coverage.

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 only 14%, so the description has to compensate, and it does well for incidentId (ownership, workspace visibility, existing-session absorption) and implicitly for agentId/prompt. But effort, modelId, and pipelineEditorContext are undocumented in both schema and description, leaving three parameters semantically opaque.

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

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

States a specific verb+resource pair ("Start a session with an agent and send it a first prompt") and pins the scope with "first prompt," which cleanly separates it from send_agent_session_message for follow-ups. An agent can identify this as the session-creation entry point without opening the schema.

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

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

Gives explicit conditions that select between two modes: without incidentId the session belongs to the caller (OAuth token required, API key gets 400), with incidentId it is incident-scoped and workspace-visible. It also warns that an incident's already-open session absorbs the prompt rather than a new one starting. It stops short of naming a sibling as the alternative for follow-up turns, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safe profile is known. The description usefully adds the side effect that the first environment in a workspace becomes the default, but says nothing about name uniqueness, idempotency, or auth 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 tight sentences with the core action front-loaded and the default-marking behavior following directly. 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?

Output schema exists so return values need not be explained, and annotations cover the safety profile. Still, for a create mutation with nested typed values and a low-coverage schema, the description leaves name constraints and value-shape expectations unaddressed.

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 only 33%: 'name' is undocumented and 'values' only carries a nested type description. The phrase 'initial set of variable values' gestures at what values means but adds no syntax, typing constraints, or name rules to compensate for the coverage gap.

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

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

States a specific verb (Create) and resource (environment) plus the initial payload it takes, which is clearer than the bare title. It does not, however, differentiate itself from siblings like update_environment or create_pipeline.

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 alternative routing (e.g., update_environment for existing environments). The default-marking note is contextual but not a usage rule.

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: append-only immutability, idempotent re-post behavior ('posting the same text twice returns the row already written'), edit-permission requirement for description, non-overwrite of human-written descriptions, and attribution to Orchestra AI vs the API key.

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 groups parameter behavior into focused paragraphs; every sentence carries operational detail. Slightly dense in places but 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?

An output schema exists so return values need not be explained, and the description still notes that the written event is returned. Combined with the mutation semantics and permission notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is already 83% (baseline 3), and the description adds meaning the schema lacks — the ORCHESTRA_AGENT_SESSION_ID source, the required coupling of AI_DIAGNOSIS_* to agentSessionId, and the duplicate-suppression behavior on comment text.

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

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

States a specific verb and resource — 'Append a row to an incident's timeline, returning the event it wrote' — which is a narrow, well-scoped operation distinguishable from sibling mutations like update_incident or merge_incidents.

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 conditions for each eventType, including that the AI_DIAGNOSIS_* types require agentSessionId and that description is only accepted with COMPLETED/FAILED. It stops short of naming alternative tools or when not to comment at all, but the mode-selection 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?

Annotations establish this is a write that is not destructive; the description goes further by disclosing that secret parameters are obfuscated in the response and that OAuth integrations return a `redirectUrl` and need a user's credential. This is genuine behavioral context beyond the annotations, missing only permissions and error behavior.

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

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

Three tight sentences, front-loaded with the core action and followed by the two constraints that actually affect a call. No wasted 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?

For a create tool with an output schema, annotations, and mostly-covered params, the description supplies the key non-obvious behavior (authSchema linkage, secret obfuscation, OAuth branch). A brief note on permissions or name collisions would complete 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?

With 71% schema coverage the schema documents most fields, but the description adds real meaning by tying `parameters` to the integration's `authSchema` and explaining the secret-obfuscation and OAuth/redirectUrl behavior for that field. callbackPath remains undocumented in both places.

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

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

States a specific verb (Create) and resource (a connection for an integration) with scope (caller's workspace), which cleanly separates it from the get/update/delete connection siblings. It stops short of naming an alternative, but the purpose is unambiguous.

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

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

Provides a concrete prerequisite workflow: `parameters` must match the integration's `authSchema`, as returned by Get an integration, which points the agent at a sibling tool first. It also flags the OAuth branch, though it offers no explicit when-not or duplicate-handling 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 only assert readOnlyHint=false and destructiveHint=false, and the description adds real context beyond that: mute claims events but raises no incident/alert, and omitting order makes the monitor claim only events no existing monitor claims. These are meaningful create-time behaviors not derivable from the annotations, though idempotency and permission requirements are unstated.

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 dense sentences, front-loaded with the verb and resource, and each clause earns its place by explaining a distinct creation behavior. Slightly clause-heavy but 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The main gap is that the counting/threshold nature of a monitor (trigger) is never mentioned in the description, though the schema describes it; overall complete enough for a nested 9-param create tool.

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

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

With only 33% schema coverage across 9 params, the description carries the load and does so for the semantically tricky ones (match, groupBy, action, order, mute), explaining how they interact rather than restating types. It leaves trigger, name, enabled and description to the schema, which largely documents trigger itself.

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

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

Uses a specific verb+resource and goes beyond the title by defining what a monitor actually is ('a rule for which failures to group into one incident, and how that incident alerts'), which the sibling list_monitors/get_monitor/update_monitor do not establish. It also surfaces a create-specific default (order puts the new monitor last), so an agent can distinguish creation semantics from the other monitor 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 implies when to reach for this tool (you are defining a new grouping/alerting rule) and explains the mute case for suppression, but it never names alternatives such as update_monitor or explicitly states when not to create. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is covered by structured data. The description adds only that the body is; it says nothing about permissions, what 'published' vs draft implies, storage-provider side effects, or account scoping, leaving meaningful behavioral gaps.

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 short sentences, front-loaded with the action and followed by the one useful prerequisite. No filler and nothing 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 an 11-parameter, nested-object mutation with only 18% schema coverage, the description is too thin; the output schema means return values need not be described, but the input-side gaps remain. An agent could not confidently populate the branch/repository/storage parameters from this definition alone.

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

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

Schema description coverage is 18% across 11 parameters, so the schema does almost none of the work; the description must compensate and largely doesn't. It only clarifies the 'data' payload shape and points at validate_pipeline, leaving alias, message, yamlPath, published, repository, defaultBranch, workingBranch, messageIsCustom, and storageProvider unexplained in both places.

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

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

States a specific verb and resource ('Create a new pipeline') and adds that the body carries a JSON pipeline definition, so the agent knows exactly what it produces. It does not, however, disambiguate from close siblings such as import_pipeline, migrate_pipeline, or update_pipeline, which an agent might reasonably confuse with it.

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

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

Gives a concrete conditional next-step: run validate_pipeline (linked as the schema-validation endpoint) first if you want to check the payload without saving. That is real routing guidance, but it only covers validation, not when to prefer create over import_pipeline/migrate_pipeline for an existing definition.

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 and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: the required markdown structure and the 409 failure mode on duplicate names, which an agent cannot infer from 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?

Three tight sentences with the core purpose front-loaded, then the format requirement, then the failure mode. No filler and nothing redundant with structured fields.

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 no explanation, and the description covers input format and duplicate-name behavior. The only meaningful gap is that it does not route the agent between create_skill and import_skill for the same task.

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 only 50%, and the required 'markdown' property has no schema description (just type and minLength). The description compensates by specifying the required frontmatter contents, which is real semantic value; the account-id parameter is already well 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 ('Create a skill') plus the source medium ('from a markdown document'), which is more informative than restating the title. It does not, however, distinguish itself from the close sibling import_skill, which also creates skills.

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 states a format prerequisite (YAML frontmatter with name/description) but gives no when-to-use guidance and never mentions the alternative import_skill or list_skills/update_skill. An agent gets no help choosing among the skill-creation siblings.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: the 403 refusal for Orchestra-managed agents and the credential-type restriction (OAuth only, API key refused). It stops short of saying whether deletion is permanent or what happens to dependent sessions/skills.

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, front-loading the core action and scope before the refusal conditions. Every clause carries an actionable constraint.

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, non-returning tool with no output schema, the definition covers scope, refusal conditions, and auth requirements. The main gap is the absence of any statement about permanence or downstream effects, which matters for an irreversible delete.

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 agent_id and X-Orchestra-Account-Id are fully documented in the schema itself. The description adds nothing about parameter formatting or account-id semantics beyond what the schema already states, so the baseline 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?

States a specific verb and resource ('Delete an agent') plus the scope the credential resolves to, which distinguishes it from the many other delete_* siblings. An agent can tell immediately what the call removes and from where.

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

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

Gives concrete preconditions: Orchestra-managed agents are refused with 403, and the call only runs for an OAuth session while an Orchestra API key is refused. It does not name an alternative tool or a when-not-to-use-this-instead-of-X case, but the eligibility rules are explicit enough to route 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?

Annotations only supply destructiveHint=true; the description adds genuinely new behavior — the deletion is total, the default environment is protected under a stated condition, and API-key credentials are refused outright. It does not say what happens to dependent objects (runs, assets) inside the environment, which is the one remaining behavioral gap.

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

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

Three short sentences, front-loaded with the action, then constraints, then auth gating. Every sentence carries a distinct operational fact; nothing is repeated from 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?

With no output schema and destructive annotations already signaling risk, the description covers the critical call-time constraints (auth mode, default-environment protection). The only omission is the return/effect surface after deletion, which is minor for a delete tool.

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

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

Schema description coverage is 50%, and the description contributes nothing about parameters. environment_id is a self-evident UUID target, and X-Orchestra-Account-Id is already richly documented in 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 ("Delete an environment entirely") with an unmistakable destructive scope. An agent can distinguish it from update_environment, get_environment, and list_environments without inspecting any schema.

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

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

Gives explicit when-not conditions (default environment cannot be deleted while others exist) and a hard auth precondition (OAuth only; refused with an API key). It does not name a sibling alternative, but the failure conditions it documents are exactly what routes an agent 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?

Annotations only say destructiveHint=true; the description goes well beyond by disclosing the cascade (asset configurations and agent integration mappings are destroyed), the default-connection guard, and the auth mode requirement. These are exactly the consequences an agent needs before invoking a destructive 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?

Two sentences, both front-loaded with the destructive scope first and the constraints second. No filler, no repetition of the title.

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

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

For a destructive tool with no output schema, it covers consequences, preconditions, and auth mode. It omits failure behavior (e.g., what error surfaces when the default-connection guard trips) and whether the deletion is reversible, which would round it out.

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 33%: the enum and connection_id carry no descriptions, while X-Orchestra-Account-Id is fully documented in the schema. The phrase 'the workspace the credential resolves to' adds useful scoping context, but the description never explains what 'integration' vs 'connection_id' select or their expected format.

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 (delete) and resource (integration connection) plus scope ('from the workspace the credential resolves to') and enumerates the cascade ('asset configurations and agent integration mappings'). An agent can distinguish this from siblings like delete_environment or delete_pipeline 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 blocking conditions: the default connection cannot be deleted while other connections exist, and the call is refused with an API key (OAuth only). It stops short of naming an alternative path (e.g., update_integration_connection or deleting other connections first), so it is clear context plus exclusions rather than full routing.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false. The description goes well beyond that, disclosing the downstream consequences (claimed incidents retain their link, new events fall through to the next matching monitor or built-in grouping rules) and a hard auth constraint (OAuth-only; refused with an Orchestra API key). This is exactly the extra context an agent needs before 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?

Three short sentences, each earning its place: action first, then side effects, then the auth gate. Nothing is redundant and the critical constraint is not 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?

With no output schema, the description carries the return/effect burden and does so: it explains the blast radius of the delete and the credential requirement. For a two-parameter destructive tool with full schema coverage, nothing material is missing.

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

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

Schema description coverage is 100% and both parameters (monitor_id, X-Orchestra-Account-Id) are fully documented in the schema, including the account-scoping nuance. The description adds no parameter-specific meaning, so the baseline 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 opens with a specific verb+resource ('Delete a monitor') that unambiguously distinguishes it from the other monitor siblings (create_monitor, update_monitor, get_monitor, list_monitors, reorder_monitors). An agent can select it 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 gives useful context about what deletion entails and its auth requirement, but never states when to choose this over alternatives (e.g., temporarily disabling via update_monitor, or how it relates to reorder_monitors). Usage is implied rather than guided.

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 safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the tool is refused under an Orchestra API key and only runs for an OAuth-signed-in user, and it enforces a one-selector rule. It does not say whether deletion is reversible or what happens to dependent runs.

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, each doing distinct work: the action, the selector rule, and the auth precondition. Front-loaded with the action and 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 destructive tool with no output schema and zero required parameters, the description covers the two things an agent most needs: how to address the target and the credential prerequisite. It omits irreversibility and side effects on pipeline runs, which is the main remaining gap.

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

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

Schema description coverage is only 20% (only X-Orchestra-Account-Id is documented in the schema), so the description carries real weight. It explains that exactly one of pipeline_id, alias, or repository+yaml_path must be supplied and how those selectors pair up, which the schema alone cannot convey since all five properties are optional and nullable with no descriptions. It stops short of format details like the UUID4 requirement for pipeline_id.

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 (Delete) and resource (a pipeline), plus the selector mechanism. It is clear what the tool does, though it does not explicitly distinguish itself from sibling mutation tools such as pause_pipeline or migrate_pipeline.

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

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

It states the invocation constraint (exactly one selector, and how to combine repository with yaml_path) and the authentication gate, which tells the agent when the call will succeed. It gives no guidance on when to delete versus pause or otherwise retire a pipeline, so usage is only partially framed.

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 destructiveHint annotation by disclosing authentication requirements (OAuth only, API key refused) and the precise blast radius of deletion (git-imported skills are removed from Orchestra but the repository file is untouched). This is exactly the side-effect context an agent needs before calling a destructive 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?

Four front-loaded sentences: the action first, then the three constraints that matter. Every sentence carries a distinct rule with no repetition 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 destructive tool with no output schema, the description covers the prerequisites (OAuth), the blocked cases (Orchestra-managed skills), and the resulting state change (repo left intact), which is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so both skill_id and X-Orchestra-Account-Id are already documented in the schema. The description adds no syntax or format guidance, so the baseline 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?

States a specific verb and resource ('Delete a skill') that is unambiguously distinct from create_skill, update_skill, get_skill, and import_skill. It doesn't explicitly name a sibling or contrast its scope, but the destructive verb leaves no ambiguity about intent.

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 when-not conditions: skills managed by Orchestra cannot be deleted, and the tool is refused under API-key auth, running only for OAuth sessions. It doesn't name alternative tools for those blocked cases, keeping it short of the top band.

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, it discloses a retention limit (7 days), truncation caps on parameter values, log tail and artifact list, and — importantly — that the response self-reports which parts were cut. That is a strong, agent-relevant behavioral disclosure that annotations 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?

Front-loaded with purpose, then payload contents, then retention/truncation caveats, then a fallback pointer. Every clause carries information; no filler.

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

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

With an output schema present the description needn't enumerate return structure, yet it still summarizes what comes back, notes retention limits, truncation behavior, and alternative tools. Nothing an agent needs to call or interpret this 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?

Two parameters at 50% schema coverage. account_id is fully documented in the schema (including API-key vs OAuth scoping), and task_run_id is self-evident from its name, but the description adds nothing about either parameter. Baseline 3 for schema-heavy coverage 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 ('Deep dive on one failed task run') and then enumerates the exact payload — status/messages, taskParameters, runParameters, upstream task statuses, log tail, artifact filenames. This clearly separates it from list_task_runs and get_pipeline_run_status.

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 routes to the alternatives ('Use download_task_run_log or download_task_run_artifact when the tail is not enough') and states the eligibility window ('queryable for 7 days only'). When-to-use and when-not-to-use are both present.

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=true; the description adds the genuinely non-obvious operational facts: the response is base64-encoded, capped at 3MiB per call, and larger files must be paginated with advancing byte ranges. That is exactly the kind of behavior an agent would otherwise get wrong.

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

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

Three tight sentences, front-loaded with purpose then the size constraint and the chunking recipe. No filler and nothing 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?

With no output schema, the description correctly supplies the return format and size limit, which is what an agent needs to consume the result. Missing is any hint that filenames come from list_task_run_artifacts and any statement of behavior once the range exceeds the file length.

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 only 20% (account_id is the sole documented param), so the description has to carry weight: it explains range_header's format and gives a concrete example. The three required identifiers (pipeline_run_id, task_run_id, filename) get no explanation, though their names are largely self-describing, so this partially compensates rather than fully.

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

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

States a specific verb (Download) and resource (task run artifact file) and adds the return encoding (base64), which cleanly separates it from the sibling download_task_run_log without the agent needing to open a schema.

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

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

Gives clear conditional guidance for range_header: use chunks when the file exceeds 3MiB, with a concrete example range value. It does not, however, point at list_task_run_artifacts as the way to discover valid filenames, so the entry path 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?

readOnlyHint already marks this as a safe read, and the description adds meaningful behavior beyond that: base64 encoding of the payload and a hard 3MiB per-call content cap with a chunking workaround. It does not state whether the log must exist or what happens on an out-of-range request, but the disclosure is well above the annotations alone.

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

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

Two tight sentences: the core action plus return format first, then the size constraint and chunking mechanic. No filler, and the most decision-relevant constraint (3MiB cap) 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 read-only download with no output schema, the description covers encoding, size limits, and paging, which is what an agent needs to call it correctly. The gap is provenance of the three required IDs and the distinction from the artifact/log-listing siblings.

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 only 20% (just account_id documented), so the description carries real burden and it does explain range_header semantics and syntax with the byte-range example. It says nothing about filename, task_run_id, or pipeline_run_id (three required IDs), leaving those entirely to inference.

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 ('Download a task run log file') plus the return encoding ('base64-encoded'), which is a genuine fact the agent needs. It does not, however, distinguish itself from near-neighbor siblings like download_task_run_artifact or list_task_run_logs, so the agent must infer the boundary.

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 real operational guidance for the chunking case (3MiB ceiling, advance range_header each call with a concrete example), which is implied usage for large files. It offers no when-to-use guidance relative to list_task_run_logs or download_task_run_artifact, so the routing decision is left to inference.

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

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

Annotations only declare readOnlyHint=true; the description adds genuinely useful behavior the annotations don't cover: secrets are returned masked, and a 404 is returned when the agent is absent from the credential's workspace. It doesn't mention rate limits or the shape of the returned prompts/settings, but this is above the annotation baseline.

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-loaded with the core action and followed by masking and error semantics. 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?

Return values are covered by the output schema, and the description adds the masking caveat and the 404 condition, which are the main things an agent needs before calling. Only the lack of alternative-tool routing keeps it from a 5.

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%, including a detailed explanation of the optional X-Orchestra-Account-Id header and its account-targeting semantics, so the schema carries parameters entirely. The description adds no parameter-level meaning, making the baseline 3 correct.

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 ('Get an agent') and adds scope detail ('with its prompts and settings'), which separates it from list_agents. It does not explicitly name a sibling to distinguish from, so it stops short of a 5.

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

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

Usage is implied: fetch a single agent by id when you already have the id. There is no explicit when/when-not guidance or routing to alternatives such as list_agents for discovery or get_agent_session for session data.

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 readOnlyHint=true, the description discloses concrete failure semantics (404 for invisible sessions, 403 for an unviewable agent) and the full visibility model — UI-started sessions are private to the user and invisible to API keys, while task-run and incident sessions are workspace-visible. That is meaningful behavioral context the 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?

Purpose is front-loaded in the first clause, and the subsequent sentences about 404/403 and visibility each carry distinct information. Slightly long for a simple fetch, but no sentence 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?

An output schema exists, so return values need no explanation, and the description covers the error and permission model an agent needs to interpret failures. What remains unstated — whether the caller should prefer list_agent_sessions for discovery — is minor for a get-by-ID tool.

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

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

Schema description coverage is 100%, so session_id and the X-Orchestra-Account-Id header are already documented, including the account/credential scoping rule. The description adds no parameter-level 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 ('Get an agent session by ID'), so the operation is unambiguous. It does not, however, distinguish itself from siblings like list_agent_sessions, get_agent_session_history_messages, or create_agent_session beyond the singular 'by ID' framing.

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

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

Usage is implied rather than stated: the caller learns it needs a session ID and that visibility depends on how the session was started, but no alternative tool is named and no explicit when-to-use/when-not guidance is given. The visibility paragraph does function as de facto guidance about when the call will succeed.

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=true, but the description adds real behavioral context: an in-progress turn is omitted until it completes, 404/403 error semantics, and detailed visibility rules (UI-started sessions are private to the user, so API keys never see them; task-run/incident sessions are workspace-wide). This goes well beyond what annotations provide.

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

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

Front-loaded with the purpose, then pagination mechanics, then error/visibility behavior. It is dense but every sentence carries actionable information; no filler, though the pagination walkthrough is long enough to border on verbose.

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

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

An output schema exists, so return values need not be spelled out, and the description covers the remaining gaps: pagination direction, cursor construction, incomplete-turn handling, and full authorization/visibility semantics. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine interpretation not in the schema: sequence IDs are '<unix-ms>-<counter>' and order as strings, which explains why before_sequence_id=current-time reads the newest turns and after_sequence_id=0 starts at the beginning.

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 page of an agent session's messages', plus the scope (whole complete turns, oldest first). It is unambiguous what the tool returns, though it never names or contrasts a sibling tool (e.g. get_agent_session, list_agent_sessions) to anchor its place in the family.

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 operating guidance: pass exactly one of before/after_sequence_id, set before_sequence_id to the current time in ms to read the latest turns, use after_sequence_id=0 to read from the start, and page with nextBeforeSequenceId/nextAfterSequenceId gated on hasPreviousPage/hasNextPage. This is effectively a usage manual for the tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely non-obvious behavior — that a session counts toward the bucket it was created in (aggregation rule), the permission prerequisite, and the request period limits. It omits pagination, rate limits, or whether results are cached/eventually consistent, so it is useful but not exhaustive.

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

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

Front-loads the core purpose in one strong sentence, then a scoped Note block for time-window behavior. It is a bit long and the Note partially restates the schema's own time_from/time_to and bucket_size descriptions, which dilutes efficiency slightly.

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 shape need not be spelled out, and the description still covers aggregation semantics, account scope, permissions, and period limits. An agent has everything needed to call it correctly with no defaults left ambiguous.

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 every parameter is already documented in the schema. The description adds real meaning beyond it by explaining the paired semantics of time_from/time_to (when only one is given the window is 30 days after/before it) and the consecutive-bucket nature of the output, which the schema does not convey.

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: retrieve input/output tokens spent by agent sessions in the account, summed across every agent and LLM connection, as totals plus time buckets. This is clearly distinguishable from siblings like list_agent_sessions or get_agent, which cover session inventory rather than usage aggregates.

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

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

Gives clear context for invocation: times are optional, omit both for the last 30 days, one-only yields a 30-day window, max 366 days, and it requires permission to view account settings. It does not, however, name an alternative tool or state when not to use this one, so it stops short of 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond that: no statement about not-found behavior, whether external IDs are resolved against a specific integration, or any rate/scope constraint. With annotations carrying the burden, this is thin.

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 filler; every clause carries 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?

An output schema exists so return values need no explanation, and readOnlyHint covers safety. For a simple lookup tool this is largely sufficient, missing only error/not-found semantics that an agent might want before calling.

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 account-scoping header is thoroughly documented in the schema itself. The description's mention of 'Orchestra asset ID or external ID' merely restates the asset_id schema description, adding no syntax or format detail. 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 (retrieve) and resource (a single asset), plus the two identifier forms accepted. The word 'single' implicitly distinguishes it from the sibling list_assets, though no sibling 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?

Usage is implied: call it when you already have an asset ID. There is no explicit statement of when to prefer this over list_assets or what happens if the ID is unknown, so guidance is only inferable.

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 the description goes beyond them by disclosing that variable values are included in the response — meaningful for a tool that may expose secrets/config. It stops short of noting authorization or account-scoping behavior, but adds real value over the 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?

A single front-loaded sentence with zero filler; the resource, identifier, and notable payload detail are all packed in without 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?

An output schema exists so return values need no explanation, and the read-only nature is covered by annotations. The description mentions variable values and the lookup key, which is sufficient for a simple single-fetch tool; only account-scoping nuance is left to 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 50%: the X-Orchestra-Account-Id header is fully documented in the schema, but environment_id carries only a uuid4 format with no description. The phrase 'by its ID' confirms environment_id's role but adds no format or lookup 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 (Fetch) and resource (a single environment) scoped by ID, which implicitly distinguishes it from list_environments. It is clear but never names the sibling it differs from, so an agent must infer the distinction itself.

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

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

'By its ID' implies the precondition that an environment_id must be known, which is usable guidance, but there is no explicit when-to-use, when-not-to-use, or reference to list_environments for discovery. Usage 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 declare readOnlyHint=true, so the safe-read profile is covered. The description adds that the response eagerly includes merge relationships and related resources, which hints at payload weight, but it says nothing about authorization scope, mutation, or errors beyond what structured data provides.

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 filler; the resource and the notable contents of the response come first. 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?

With an output schema present and annotations covering the safety profile, the description need not explain return values, and it doesn't over-reach. It is nearly complete for a simple by-ID getter, losing a point only for the absence of any when-to-use framing relative to the large set of incident siblings.

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 (incident_id, X-Orchestra-Account-Id) are documented in the schema itself, including the account-scoping rules. The description adds no parameter meaning beyond that, so the baseline 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 states a specific verb and resource ('Fetch a single incident') and adds the shape of the payload (merge relationships, summary counts, related resources). The word 'single' implicitly distinguishes it from list_incidents, but it does not explicitly name or contrast any sibling tool.

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

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

Usage is only implied: an agent can infer this is the by-ID lookup for one incident versus list_incidents. There is no explicit statement of when to reach for this tool, no prerequisites, and no routing away from merge_incidents, list_incident_events, or update_incident.

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 readOnlyHint annotation already establishes this as a safe read, so the description's burden is lighter; it still adds real value by disclosing that the payload can expire and then returns 410. It says nothing about permission requirements or payload size, but the expiry disclosure is a meaningful trait not present in 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, zero filler, with the resource and its scoping constraint front-loaded and the error behavior appended. 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?

An output schema exists, so return-shape detail is unnecessary; the description covers purpose, the precondition for a valid call, and the notable failure mode. For a single-row read with a fully documented schema and annotations, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics for incident_event_id by narrowing it to rows where hasExternalEvent is true, which the schema's terse 'Timeline row ID.' does not convey. The account-override parameter is left to the schema, which documents it thoroughly.

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 (fetch) and resource (the raw JSON an external system sent) scoped to exactly one row of an incident timeline, and adds the discriminator 'a row whose hasExternalEvent is true'. This lets an agent distinguish it from list_incident_events or get_incident 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?

It gives a concrete pre-condition for use (the timeline row must have hasExternalEvent true) and states the failure case (410 after expiry), which is clear operational context. It does not, however, name an alternative tool or say what to do when the row lacks an external event, so it stops short of explicit 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, so the safety profile is covered. The description adds genuine behavioral value beyond that: a workspace that has never saved settings receives defaults rather than an error or null, which tells the agent it can always expect a usable response. It does not discuss permissions or response shape, but the annotation already covers read-only semantics.

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 zero waste; the content enumeration is front-loaded and the defaults caveat follows naturally. 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?

An output schema exists, so the description need not explain return values, yet it helpfully summarizes the settings categories. Combined with the readOnlyHint annotation and full parameter coverage, the definition is essentially complete; only explicit usage routing is absent.

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

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

Schema description coverage is 100% and the single parameter (X-Orchestra-Account-Id) is fully documented in the schema, including its anyOf/null handling and API-key vs OAuth constraints. The description adds nothing about parameters, so the baseline 3 is correct when the schema does all the work.

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

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

The description states a specific verb+resource (get the workspace's incident settings) and enumerates exactly what those settings cover: whether incidents are on, which failures raise one, and how they alert. This distinguishes it from siblings like get_incident (a single incident) and update_incident_settings (the mutation counterpart).

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

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

Usage is implied by the read-only nature of the tool, but there is no explicit when-to-use guidance, no mention of update_incident_settings as the write alternative, and no stated prerequisites. The 'never saved gets the defaults' note is behavioral rather than 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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely useful context about the returned payload: auth and job schemas are included, and it explains how to interpret auth_schema entries (name = connection field, format: password = secret). It doesn't mention auth requirements or rate limits, but the return-shape interpretation is real added 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?

Two tight sentences with the core purpose front-loaded and the payload-interpretation tip following immediately. Every sentence earns its place, 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?

An output schema exists, so return values need not be documented, yet the description still supplies helpful interpretation of auth_schema fields. For a simple single-parameter read tool this is nearly complete; only explicit sibling routing is absent.

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

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

Schema description coverage is 0% for the single enum parameter, but the enum values are self-explanatory identifiers. The description only says 'by its identifier' without adding format, casing, or matching rules, so it adds little beyond the schema.

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

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

States a specific verb and resource ('Fetch a single integration by its identifier') and uses 'single' to implicitly separate it from the listing siblings. It does not name a specific sibling to differentiate from, so it falls just short of a 5.

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

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

Usage is only implied: the agent can infer this is the tool for retrieving one integration's details rather than a list. There is no explicit when-to-use or when-not-to-use guidance relative to siblings like get_integration_connection or list_integration_connections.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely new behavior: the response includes auth parameters, and secret auth parameters are obfuscated. It also discloses the workspace/credential scoping rule, which is not derivable from annotations.

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

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

Two tight sentences with no filler; the scope (which connection, which workspace) leads, and the obfuscation caveat follows. Both sentences carry information an agent needs.

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

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

An output schema exists, so return-shape detail is unnecessary, and readOnlyHint covers safety. The description handles scoping and the secret-obfuscation caveat well; only error/not-found behavior for a bad connection_id is left 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 coverage is only 33% (just X-Orchestra-Account-Id), so the description is expected to compensate for 'integration' and 'connection_id' and does not. It touches account/workspace resolution only tangentially via 'the workspace the credential resolves to', leaving the two required parameters undocumented beyond their names.

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 ('Fetch') plus resource ('a single integration connection') and scopes it to the credential's workspace. The word 'single' implicitly contrasts with list_integration_connections, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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 says what it does but never says when to reach for it over list_integration_connections (e.g., when you already hold a connection_id) or how to obtain a valid connection_id. There are no exclusions, prerequisites, or alternative-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 declare readOnlyHint=true, so the safety profile is covered. The description adds the useful scoping detail that the workspace is derived from the credential, but says nothing about what 'state' contains, error behavior, or the state-aware concept implied by the tool name.

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 scope front-loaded and no filler. It is efficient, though a clause clarifying 'state' vs 'connection' would have earned 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?

An output schema exists, so return values need not be explained, and readOnlyHint covers safety. Still, the core ambiguity of what 'stored state' means relative to the neighboring integration tools is left unresolved for a tool whose name implies a state-aware special case.

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 50%: the integration enum is self-documenting via its value list, and X-Orchestra-Account-Id carries a rich schema description. The description adds no parameter detail beyond echoing the credential/workspace resolution, so it neither compensates for nor extends the schema meaningfully.

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 (fetch) and resource (stored state for a given integration), scoped to a workspace. It is understandable on its own, but it never distinguishes itself from siblings like get_integration or get_integration_connection, leaving the boundary between 'state', 'connection', and 'integration' unclear.

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 get_integration or list_integration_connections, no prerequisites, and no exclusions. Usage is only implied by the description's mention of 'stored state'.

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, so the safety profile is covered. Beyond that the description adds almost nothing: it doesn't say whether it errors when the monitor is missing, whether the result is cached, or what 'definition' excludes (e.g. runtime status).

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 padding — efficient and easy to scan. It is arguably too terse for what it omits, but as a structure it wastes nothing.

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

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

With an output schema present, return values need not be explained, and the annotations plus full schema coverage carry most of the load. Still, for a lookup tool it says nothing about failure behavior or account-scoping implications beyond what the schema already states.

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

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

Schema description coverage is 100%, with monitor_id and the X-Orchestra-Account-Id scoping/credential semantics fully documented in the schema itself. The description adds no additional parameter meaning, 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 (fetch) and resource (a monitor's definition), and the word 'single' implicitly distinguishes it from the sibling list_monitors. It does not, however, name or explicitly contrast with any sibling tool.

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 and no explicit alternative is named; the agent must infer from 'single' that list_monitors is the bulk counterpart. There are no prerequisites, exclusions, or conditions 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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description contributes the mutually-exclusive selector constraint that the empty required list does not enforce. It still omits what happens when zero or conflicting selectors are supplied, and whether branch/commit/version can be combined, so it is not fully 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?

Two tight sentences with the purpose front-loaded and no filler. The second sentence partly repeats parameter names already visible in the schema, which keeps it from being maximally economical.

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 values need no explanation, annotations cover read-only safety, and the schema fully documents parameters; the description adds the missing selector-exclusivity rule. It could still note the failure mode for an invalid selector set or point to the sibling used for data/runs retrieval.

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 each selector parameter is documented in the schema, including the repository/yaml_path pairing. The description restates the selector list and adds the exactly-one rule, but supplies no format or semantics beyond what the schema already carries, 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?

"Fetch a single pipeline" gives a specific verb and resource, and "single" implicitly contrasts with the sibling list_pipelines. It does not, however, distinguish itself from get_pipeline_data or pipeline_context, which an agent would have to 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?

The description states the invocation rule (provide exactly one selector) and enumerates the valid selector combinations, which is real usage guidance. It gives no when-to-use vs when-not-to-use guidance relative to siblings like get_pipeline_data or list_pipelines, leaving selection 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?

readOnlyHint=true already declares this a safe read. The description adds that it returns the full definition and can pin to a specific revision, which is useful, but it says nothing about the git-backed vs versioned YAML distinction or the account-scoping behavior that the schema only hints at. Adequate but not rich.

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 primary selector front-loaded and the optional revision path second. No filler, though the second sentence compresses several distinct selector types into one clause.

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, and the schema fully documents the parameters. The description is complete for the core flow, with only minor gaps around the yaml_path/repository pair and account-override semantics, which the schema already covers.

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 eight selectors. The description repeats the primary ones (pipeline_id, alias, version, branch, commit) without adding format or mutual-exclusion rules, and omits yaml_path/repository pairing entirely. 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 ('Fetch the full pipeline definition') and clarifies that selection is by pipeline_id or alias, with optional revision selectors. It partially distinguishes itself from siblings like get_pipeline by emphasizing the full definition plus revision loading, though it never names those siblings explicitly.

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

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

It explains how to select a pipeline and that version/branch/commit load a specific revision, which implies usage. But it gives no guidance on when to prefer this over get_pipeline, list_pipelines, or pipeline_context, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to re-establish safety. It adds that the output is a lineage graph URL, but it does not disclose details like whether the pipeline run must exist or how the URL is formatted. With annotations in place, this is acceptable but minimal.

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, direct sentence with no filler. It front-loads the action and target, and every word 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?

This is a low-complexity, single-parameter, read-only tool with an output schema available. The description covers the core purpose sufficiently. The only notable gap is not explaining the provenance or format of pipeline_run_id, but the output schema and annotation coverage compensate for most of what an agent needs.

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

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

Schema description coverage is 0%, so the description carries responsibility for explaining the single parameter, pipeline_run_id. It does not mention where the ID comes from, what format it expects, or how it is used. The parameter name is self-explanatory, but the description still adds no parameter-level 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 uses a specific verb, 'Build', and a clear target, 'the URL of a pipeline run's lineage graph in the Orchestra UI.' This distinguishes it from sibling tools that retrieve statuses, logs, or artifacts, since none of them construct a UI URL.

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 no explicit guidance about when to use this tool versus alternatives like pipeline_context or get_pipeline_run_status. The intended use is implied, but there are no exclusions, prerequisites, or alternative tool mentions.

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 the description adds no behavioral context beyond that — no mention of what happens if the run ID is unknown, retention windows, or polling semantics. For a trivially safe read tool the annotations carry the safety profile, but the description contributes essentially nothing new.

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 that states the purpose up front with no filler; the only extra element is a documentation link, which is cheap and potentially useful. Nothing needs trimming.

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 described, and both parameters are covered by the schema with annotations covering the safety profile. What is missing is error/edge-case behavior (unknown run ID, permission failure) and how this relates to adjacent per-run tools.

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

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

Schema description coverage is 100%, with pipeline_run_id (uuid4) and X-Orchestra-Account-Id both fully documented in the schema, including the multi-account rules. The description adds no parameter meaning beyond the schema, so the baseline 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 states a specific verb (Retrieve) and a specific resource (status details for a single pipeline run), and the word 'single' implicitly separates it from list_pipeline_runs. It does not, however, differentiate against other per-run siblings such as get_pipeline_run_lineage_url or list_task_runs_for_pipeline_run.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g., the run must be complete vs. in-flight), and no exclusions or named alternatives. The only hint is the word 'single', which an agent must infer means 'use this instead of list_pipeline_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?

The readOnlyHint=true annotation already establishes this is a safe read. The description adds the useful detail that the response includes the full markdown body (as opposed to a summary), but says nothing about auth scoping, error behavior, or how it differs from sibling reads beyond content depth.

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 carries the verb, resource, and the one distinguishing payload detail. Nothing is padded or 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 simple single-record read with 100% schema coverage, an output schema, and a readOnly annotation, the description covers what is needed. It could be richer only by routing to sibling read tools, which is a minor gap for such a simple operation.

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

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

Schema description coverage is 100%, with skill_id and X-Orchestra-Account-Id fully documented in the schema, so the baseline is 3. The description adds no parameter-level 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?

States a specific verb and resource ('Fetch a single skill') and adds the notable scope detail that the full `markdown` is included. The word 'single' implicitly distinguishes it from list_skills, though no sibling 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?

Usage is only implied: an agent can infer this is for retrieving one skill when it has a skill_id. There is no explicit statement of when to use this versus list_skills or the agent-scoped list_agent_skills, and no exclusions.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the mutation nature is known. The description adds that the source is Git-backed, but says nothing about whether an existing pipeline is overwritten, what happens on conflict, which credential/account is required, or whether the import is synchronous.

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

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

A single tight sentence with the operation front-loaded and no filler. Nothing in it is wasted, though the terseness is also the source of the gaps 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?

An output schema exists, so return values need not be explained, but for a 7-parameter mutation tool with 14% schema coverage the description is far too thin. It omits conflict/overwrite behavior, auth context, and the meaning of nearly all parameters.

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 only 14% (just X-Orchestra-Account-Id), leaving six parameters undocumented. The description only implies the 'repository' parameter via the phrase 'from a repository' and explains none of yamlPath, defaultBranch, workingBranch, storageProvider, or alias.

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 (Import) and resource (a Git-backed pipeline definition) with a clear source (a repository) and destination (Orchestra). It does not, however, differentiate itself from close siblings such as create_pipeline, migrate_pipeline, or validate_pipeline, which an agent must choose between.

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 says nothing about when to import rather than create or migrate a pipeline, and gives no prerequisites (e.g. repository access, credential setup). Usage must be inferred entirely from the name and the sibling list.

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 and destructiveHint=false, so the description carries real weight. It discloses the post-import immutability constraint ('read-only: edit the file in the connected repository instead') and specific failure codes (422 no git provider, 404 file not on branch), both genuinely useful beyond structured data. It does not contradict the write annotation, since the write is the import itself, not the skill's later mutability.

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

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

Three tight sentences: action + source first, then the read-only consequence, then error conditions. Nothing is padding and each sentence carries distinct 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, return values need no explanation, and the description covers the source location, the immutability constraint, and the two most likely failure modes. The residual gap is parameter format detail for path/repository/defaultBranch, which the schema does not supply either.

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 only 25% — the one documented field (X-Orchestra-Account-Id) is fully explained in the schema, while path, repository, and defaultBranch have no descriptions. The prose loosely implies path is a markdown file location and defaultBranch identifies a branch, but adds no format guidance (relative vs absolute path, repo slug vs URL), so it only partially compensates for the gap.

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

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

States a specific verb (import) plus resource (skill) and names the exact source: a markdown file in the workspace's connected git repository. It also implicitly differentiates from create_skill by noting the imported skill carries the same frontmatter as a created one, so an agent can tell the two paths apart.

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: this is the right tool when the skill already lives as a markdown file in the connected git repo, and it explicitly redirects edits to the repository file rather than the tool. It does not compare against create_skill/list_skills alternatives, nor state prerequisites beyond the implicit git connection (which surfaces only as a 422 error code).

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 readOnlyHint, so the description usefully adds that an API key yields exactly one workspace while an OAuth token yields the granted workspaces still matching the user's membership. It also names the downstream header mechanism (X-Orchestra-Account-Id), which is real behavioral context beyond the 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?

Two short paragraphs, scoping behavior front-loaded ahead of the downstream usage note. Every sentence carries information and none 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?

An output schema exists, so return-value structure needn't be re-explained. Combined with the annotation and the credential-dependent scope plus follow-up usage guidance, an agent has everything needed to call and use 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?

There are zero input parameters, so the baseline is 4. The description adds meaningful semantic context by clarifying that a returned id is the selector used on workspace-scoped calls, tying the output back to how it is consumed.

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 ('Lists the workspaces this credential can act on') and precisely distinguishes how the result set varies by credential type (API key vs OAuth). No sibling tool lists accounts, and the scope is unambiguous.

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

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

It explains the when and why clearly through the credential-type behavior and tells the agent what to do with the result ('Pass a returned id to select the workspace...'). There is no explicit comparison to an alternative, though no analogous sibling exists to route away from.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds genuine behavioral detail beyond that: `url` is a short-lived link and is omitted for an uploaded avatar still being scanned for malware. This explains a field that may be unexpectedly absent, which annotations cannot convey.

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

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

Three tight sentences with no filler, front-loading what is listed before covering how to use `path` and the caveat about `url`. Every sentence carries distinct 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?

An output schema exists, so return values need not be fully spelled out, and the one optional parameter is schema-documented. The description covers the non-obvious gaps (scope, how to reuse `path`, transient `url`), making it sufficient to call the tool correctly.

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

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

Schema coverage is 100% and the single parameter (X-Orchestra-Account-Id) is fully documented in the schema; the description says nothing about it. Baseline 3 applies since the schema does the heavy lifting, though the description does clarify the semantics of returned `path`/`url` fields.

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 ('List the avatars an agent can use') and immediately narrows scope to two sources: Orchestra's stock avatars and workspace-uploaded ones. No sibling tool in the list deals with avatars, so the agent can place it unambiguously.

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

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

Gives actionable downstream context: 'Pass an entry's `path` as `avatar_path` when creating or updating an agent,' which ties it to create_agent/update_agent workflows. It stops short of explicit when-not-to-use guidance or naming an alternative, but the usage context 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?

readOnlyHint already establishes the safe-read profile, so the description's value is in the extra detail it supplies: the exact shape of the returned integration key (`<INTEGRATION>_<connection id>`) and the 404 error condition when the agent is absent from the credential's workspace. That is meaningful context beyond the annotations, though nothing is said about pagination or empty results.

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 core purpose front-loaded and the return-format detail immediately after. No filler or restatement of the title.

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

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

With an output schema present and read-only annotations covering the safety profile, the description supplies what's missing: key format and the 404 case. Complete enough to call correctly, though it could note paging behavior for large integration lists.

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 paging and the account header. The description only tangentially adds meaning by tying the lookup to the workspace the credential resolves to, which mildly reinforces the account-scoping semantics of X-Orchestra-Account-Id.

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: listing the integration connections a given agent can use. The "an agent can use" qualifier distinguishes it from the sibling list_integration_connections, but the description never explicitly names that alternative, so a reader must infer the boundary.

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 and no named alternatives. The agent is left to guess whether this or list_integration_connections / set_agent_integrations is the right call in a given situation. The 404 note is a behavior, 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 only declare readOnlyHint=true; the description adds real context beyond that: results are permission-filtered to what the caller may view, Orchestra-managed agents are included by default, and prompts/secrets are deliberately omitted. It doesn't discuss pagination or result ordering, which is a mild gap for a list 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?

Two compact sentences with no filler; the scope constraint (credential's workspace, visibility filter) is front-loaded and the exclusion/redirect follows immediately.

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 values need not be explained, and the description covers scope, filtering, and omissions well. The only missing element is paging behavior for a paginated listing, though the schema documents page/page_size adequately.

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 (including the X-Orchestra-Account-Id account override) is already documented in the schema. The description gestures at the orchestra_managed concept ('including those managed by Orchestra') but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (list agents) plus precise scope: the workspace the credential resolves to, including Orchestra-managed agents, filtered by caller visibility. It also distinguishes itself from get_agent by naming what that sibling is needed for (prompts and secrets), so an agent can route 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?

Clear context for when to use this tool and an explicit redirect: 'get an agent by id for those' (prompts/secrets). It also implicitly scopes to viewable agents. It stops short of stating when-not-to-use cases such as preferring list_agent_* sub-resources, so it is strong but 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?

Goes beyond readOnlyHint by explaining the visibility model: user-started sessions are private to the user, API keys never see them, and task-run/incident sessions are workspace-visible. This is valuable behavioral context. Lacks details on pagination, default limits, or response shape, but those are partly covered by schema and output schema.

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

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

Two clear sentences that front-load the core action and scope, then explain visibility. Efficient, no wasted words, though the visibility explanation could be slightly more compact.

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 essential visibility constraints, which are crucial for an agent to correctly interpret results. With a rich schema and output schema handling parameters and return values, the description is nearly complete for a list tool. Minor gaps remain around pagination defaults, but those are schema-documented.

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 documents all 8 parameters thoroughly. The description adds no param-specific info like syntax or format details, which is fine given the baseline of 3 when schema does the heavy lifting.

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

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

States a specific verb and resource ('List the agent sessions'), specifies the scope (the workspace the credential resolves to), and the ordering (most recently updated first). It's clearly distinguishable from siblings like get_agent_session or create_agent_session.

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 doesn't explicitly state when to use this tool vs alternatives like get_agent_session (singular) or list_agents. The visibility rules imply usage context, but there is no direct when/when-not guidance or named alternatives.

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