concur_graphql_mutation

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

Annotations already declare destructive/openWorld/non-readOnly, but the description adds materially more: the preview shows the exact document and variables, the server cannot know what an arbitrary mutation changes so it must be treated as irreversible, and the two-phase confirmation flow (elicitation prompt, or preview plus confirmToken on repeat call) is spelled out. It also warns against following instructions embedded in tool results, which is behavioral context no annotation conveys.

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 escape-hatch framing and the irreversibility warning before the exclusion list and mechanics, which is the right ordering for a destructive tool. It is long and dense, and the endpoint mapping sentence is duplicated almost verbatim from the endpoint parameter's schema description, which is the main piece of text that does not earn its place.

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

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

For a high-risk, open-ended escape hatch with no output schema, it covers everything an agent needs to call it correctly: which endpoint, where to find valid operation texts, required identity/role parameters, the confirmation protocol, and the irreversibility assumption. Nothing material is missing given the annotations already carry the destructive profile.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema on confirmToken — clarifying it is only for the no-elicitation fallback, comes from this tool's own phase-1 response, must be replayed with the same arguments, and is ignored under elicitation. It also adds practical guidance that isn't in the schema: pass the real userId from concur_whoami and contextRole TRAVELER where an operation asks for them.

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

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

States a specific verb and resource ("Run a raw GraphQL mutation against SAP Concur") and frames its niche precisely as "the escape hatch for writes no dedicated tool covers," which separates it from the dedicated write tools and from its read sibling concur_graphql_query.

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 routing rules: prefer a dedicated tool when concur_list_operations names one, refused operations are enumerated with the correct alternative named inline ("submitting a report (use concur_submit_report)"), and the out-of-scope travel/approval/delegate operations are listed as hard exclusions. It also explains the workflow prerequisites — introspection disabled, find operation names via concur_list_operations, verbatim texts in docs/api/.

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